Home

Virtuoso User Manual

Contents

1. Example VIRTUOSO TL Debugger 3 09 NODE 1 NODE1 TASK STATES Name PrioState O TLDEBUG 11 1 POLLESC 1 Waiting for Timer 2CONIDRV 2 Waiting for Resource 3 CONODRV 3 Waiting for Dequeue 4 GRAPHDRV 4 5 WLMON1 10 Waiting for Resource 6 MASTER 5 Waiting for Sema 7 WLGEN 20 Waiting for Dequeue 8 DIGIT11 15 Waiting for Resource 9DIGIT13 13 Waiting for Sema 10 DIGIT14 12 Waiting for Sema 11 DIGIT15 11 Waiting for Sema 12 DIGIT22 14 Waiting for Sema 13 DIGIT24 12 Waiting for Sema 14 DIGIT31 15 Waiting for Resource 15 DIGIT33 13 Waiting for Sema 16 DIGIT35 11 Waiting for Sema 17 DIGIT42 14 Waiting for Sema The legitimate state descriptions are Task suspended by debugger Inactive Terminated Suspended Waiting for Timer Waiting for Driver Waiting for Datamove Waiting for Event Waiting for Enqueue Waiting for Dequeue Waiting for Send Waiting for Receive Waiting for Sema Task active Task not started Task terminated Task suspended Sleep state Waiting on return of driver function Waiting on return of KS_MoveData may be part of service using mailbox Waiting on return of KS_EventW Waiting on return of KS_Enqueue W T Waiting on return of KS_Dequeue W T Waiting on return of KS_Send W T Waiting on return of KS_Receive W Waiting on return of KS_Wait T T A T Copyright 1996 Eonic Systems Virtuoso Referenc
2. n TYPE keyword for node definition ID symbolic name of the node LOCATION symbolic name of board and site PRI or SEC if any MEMORY CONTROL WORDS target dependent The following three values are required by all C40 boot loaders LBCR local bus control register Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 123 Hostserver and netloader 12 2 4 12 2 5 GBCR global bus control register IACK iack address FILE the executable file to be loaded on the node Note on some recent board specific ports two files need to be defined The first one is the bootstrap loader while the second one is the executable image Root node definition ROOTNODE lt symbolic name of root node gt Example ROOTNODE NODE The root node is the node that is directly interfaced to the host When booting the root node is loaded first then all others are booted from one of their comports When the application is running driver tasks placed on the root node will interface to the server program on the host and provide services for the C40 network List of comport links available for booting Example NODE PORT NODE PORT BOOTLINK NODE1 1 NODE2 4 BOOTLINK NODE2 1 NODE3 4 BOOTLINK keyword for bootlink definition NODE symbolic name of node PORT comport number You don t have
3. FIGURE 3 An execution trace of a hypothetical Virtuoso program segment In Figure 2 we illustrate a hypothetical example that illustrates the interac tion between the different levels The order of magnitude of the timestep is indicated in microseconds As can be seen any lower level has an effective higher priority than any higher level and can preempt an activity executing at any higher level The processor accepts an interrupt 1 This can be an external interrupt a comport interrupt or a timer interrupt The interrupt is passed on to a higher level for further processing This disables interrupts for less than one micro second on a C40 or about 1 5 microseconds on a 96K P1 16 Virtuoso User Manual Copyright 1996 Eonic Systems Virtuoso an overview An ISR enters ISR1 level 2 This can only be to further process an interrupt accepted by the ISRO level On processors with support for multi level inter rupts an ISR executing at level 1 an be preempted by an interrupt of a higher priority The microkernel is invoked 3 This can happen as a result of signal coming from an ISRO a microkernel service request from a task a task entering a wait state or an event raised by an ISR1 or a nanokernel process The micro kernel is a nanokernel process that waits on any of these events to happen A nanokernel process is executed 4 In this example an ISRO could have triggered a receiver driver that
4. and put the other definition in comment VIRTLIB LIBS virtos lib M3 28 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Motorola 96K DSP whereby is the comment sign Then remake the application just by doing MAKE lt Enter gt LINKF ILE List of the object versions of all source files to be linked along LOCAT CMD Locator command file Change the memory reservations in this file accord ing to your memory needs If the locator pass of the linker finds it has not enough Y memory to place the data sections it starts locating sections in the YR memory space from address 7ff on or right after the reservation for the ROM space 400 to 7ff This very annoying locator problem results in data sections being placed in nonexisting memory The only known way to circumvent this problem is to change the other reservations so that every section can be placed in existing memory spaces YOUR SOURCE FILES In the examples this is just test c After you have done make ing your application you should run the batch file MAKESYM BAT contained in the BIN subdirectory from the directory where your application is built This batch file makes the necessary symbol files ADR and SYM starting from the MAP file The server program will not start your application if you omit this step Copyright 1996 Eonic Systems Virtuoso Binding Manual M3 29
5. if KS_SendWT BOX1 2 amp msg 100 RC_OK printf MSG sent OK receiver was waiting n else printf Timed out no receiver n KS_Send KS_SendWT KS_ Receive KS_ ReceiveW KS_ ReceiveW Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 89 Alphabetical List of Virtuoso microkernel services e SPECIAL NOTES The size member is the number of 8 bit bytes in the message Care needs to be taken when specifying sizes on systems where characters are stored one per word or where sizeof does not return the number of 8 bit bytes in a type P2 90 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services 11 53 e SUMMARY e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTE KS SetEntry Set the entry point of a task Task void KS_SetEntry K_TASK task void function void The KS_SetEntry function will set the entry point of a task to a given func tion At the next KS_Start call for the given task the task will execute the specified function NONE extern void new_function void K_TASK LOWTASK KS_SetEntry LOWTASK new_function KS_Abort LOWTASK KS_Start LOWTASK starts in new_function KS_ Start KS_ Aborted You can only set the entry point of a local task Attempting to set the entry point of a non local task w
6. dt time object action 1004 8181 67020119 idle Swapped in 1 005 10002 67030121 Event 48 1006 9998 67040119 Event 48 1007 10000 67050119 Event 48 1008 10000 67060119 Event 48 1009 10000 67070119 Event 48 1010 10000 67080119 Event 48 1011 2538 67082657 Event 14 012 89 67082746 GRAPHDRV Event 013 102 67082848 GRAPHDRV Swapped in 1015 139 67083142 TLDEBUG Dequeue 1016 114 67083256 TLDEBUG Swapped in 017 156 67083412 TLDEBUG LOCK_REQ 018 129 67083541 TLDEBUG Resource 1019 137 67083678 GRAPHDRV Swapped in 1020 148 67083826 GRAPHDRV UNLOCK 1021 133 67083959 TLDEBUG Resource 1022 106 67084065 TLDEBUG Swapped in 1023 145 67084210 TLDEBUG GROUPOP The trace above retraces the execution history on a 40 MHz TMS20C40 at the moment the task level debugger was called Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 163 Debugging environment under Virtuoso 15 2 11 15 2 12 15 2 13 Note On target boards with no high precision timer Virtuoso often implements a low resolution timer e g with a tick of 1 millisecond As a result the timing interval rather coarse grain and it is the order of the events that is the most relevant information Mailboxes This command lists the current requests for sending and receiving mes sages in a particular mailbox Name the mailbox symbolic name Count the number of current entries Waiters List of waiting
7. y Event Nano Kernel Global Interrupts Enabled Global Interrupts Disabled HW Interrupt FIGURE 2 Multi level support mechanism in Virtuoso LEVEL 2 ISR1 level The ISR1 level is invoked from ISRO It is used for handling the interrupt with global interrupts enabled An ISR1 routine permits to raise an Event for a waiting task An ISR1 routine must itself save and restore the context but permits interrupts to be nested An ISR1 routine can be replaced by a nanokernel process that is easier to program as the nanokernel takes care of the context switch When the processor supports multi level interrupts the ISR1 level can be viewed as having itself multiple levels of priority The use of priority however should be limited only to determine what interrupts are masked out when a given interrupt occurs LEVEL 3 The nanokernel level Processes This is a major breakthrough for DSP processors The nanokernel level is composed of tasks with a reduced context called processes These deliver a P1 14 Virtuoso User Manual Copyright 1996 Eonic Systems Virtuoso an overview task switch in less than 1 microsecond on a C40 Several types of primitives are available for synchronization and communication Each process starts up and finishes as a assembly routine can call C functions and leaves the interrupts enabled Normally one will only write low level device drivers or a very time critical code at this le
8. tx_data word0O pointer to tx data buffer tx_count word 0 tx word counter void seriall_send void P Set up tx_data and tx_count and send the first word The ISR will be called to handle the rest text Copyright 1996 Eonic Systems Virtuoso Binding Manual Tli 11 Virtuoso on the Texas Instruments TMS320C30 amp C31 _seriall_send 1diSP AR2 get first argument on stack 1ldi AR2 ARO pointer to packet 1di ARO AR1 get first word point to next sti ARO tx_data save pointer for isr ldi AR1 RO extract length and OFFh RO subi 1 RO number of word remaining sti RO tx_count save length for isr ldi portilbase ARO transmit first word sti AR1 ARO TXDATA rets 3 Interrupt handler An interrupt will be generated for each transmitted word Send a signal to the kernel if all words have been transmitted otherwise send next word and return from interrupt text _serltx_irqh push ST save minimal register set push RO pushf RO ldi tx_count RO get word count test if zero bz txl_l last word transmitted signalkernel subi 1 RO decrement word count sti RO tx_count and write it back push ARO save some more registers push AR1 ldi tx_data ARO pointer to next word ldi ARO AR1 read word increment pointer sti ARO tx_data store updated pointer A ldi portlbase ARO address of tx port AR1 AR
9. 29 11 KS EnablelSR Enables an ISR to be triggered by an interrupt void KS_EnableISR int IRQ void ISR void int PrioLevel int Mode This C callable kernel service installs an ISR by writing a JSR instruction at the appropriate place in the interrupt vector table and setting the IPR register of the processor with the correct bit values for the actual interrupt This ser vice may be used to install following interrupts together with their priority level and interrupt mode if appropriate IRQA IRQB IRQC DMA Channel 1 DMA Channel 2 Host A Command Host B Command Other interrupts can also be installed by this service but for them the priority level and interrupt mode is not applicable and the arguments PrioLevel and Mode are not used NONE extern void ISRDMACh1 void KS_EnableISR 9 ISRDMACh1 2 0 The Nanokernel No description since the Nanokernel is not yet completed for the DSP96002 release of Virtuoso M3 22 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Motorola 96K DSP 29 12 1 KS EventW Brief 2 2 0 Waits on event associated with ISR KS_EventW int IRQ e Description This C callable kernel service can be used by a an application task to wait for a signal given by an ISR It forms a pair with kernel service Fkernel_sign_entry e Example Seealso Fkernel_sign_entry e Sp
10. SEEALSO e SPECIAL NOTES KS _ RestartTimer Restart a timer Timer void KS_RestartTimer K_TIMER timer K_TICKS delay K_TICKS cyclic_period The KS_RestartTimer service restarts a timer with a new delay and optional cyclic period It does not matter if the timer has already expired or not The semaphore parameter given in a previous KS_StartTimer call remains in effect NONE K_TIMER xtimer4 K_SEMA TRIGGER timer4 KS_AllocTimer KS_StartTimer timer4 10 0 TRIGGER signal in 10 ticks KS_RestartTimer timer4 10 0 restart countdown KS_StartTimer KS_StopTimer KS_RestartTimer should be used only after a KS _StartTimer call for the same timer otherwise the timer semaphore will be undefined Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 83 Alphabetical List of Virtuoso microkernel services 11 48 e SUMMARY e CLASS ey ee ee e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO KS Resume Resume a task Task void KS_Resume K_TASK task The KS_ Resume microkernel service clears the SUSPENDED state of a task caused by a KS_Suspend microkernel service NONE K_TASK tapereader KS_Resume tapereader resume the task KS_ResumeG KS_ Suspend KS SuspendG P2 84 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso mi
11. create a pointer to the command packet CP1P amp CPI1 initialize CP1 for a KS_Signal SEMA1 service CP1 Srce 0 CP1 Comm SIGNALS CP1 Args sl sema SEMA or for a KS_SignalM SLIST1 service CP1 Scre 0 CP1 Comm SIGNALM CP1 Args s1 list SLIST1 install the ISR KS_EnableISR my_isr For the ISR something like the code listed below will be required extern _CP1P extern _K_ArgsP global _my_isr _my_isr 14 dm _K_ArgsP 14 contains pointer to channel 12 dm _CP IP r2 contains data PRHI_PSH signals semaphore Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 2 17 Virtuoso on the ADSP 2106x SHARC 21 8 21 8 1 21 8 2 Additional microkernel features on the 21060 Use of the PC stack and the counter stack It is possible to use these stacks at the task level They are part of the nor mal task context and are swapped accordingly This implies that it is also allowed to use all optimisation levels provided for by the compiler There is one restriction to the use of the PC stack the nanokernel and microkernel use it internally so all tasks should leave 2 entries on the PC stack for internal use Extended context It is also possible to use the circular buffer mechanism at the task level Because this implies adding the m and b registers to the task swap set CSAVE considerably increasing the time necessary to perform a task sw
12. The KS_TestW microkernel service is used to make a task wait for a speci fied event to occur The event must be associated with the given semaphore If the semaphore count is greater than zero the call returns immediately and the semaphore count is decremented by one Otherwise the calling task is put into the semaphore waiting list in order of the task priority RC_OK K_SEMA ADC_SEMA KS_TestW ADC_SEMA KS _ Test KS_TestWT KS_TestMWw KS _ TestMWT KS Signal KS_SignalM In Virtuoso Micro this service is implemented as a macro P2 110 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services 11 72 e SUMMARY e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES KS TestWT Test a semaphore with time out Semaphore int KS_TestWT K_SEMA sema K_TICKS ticks The KS_TestWT microkernel service is used to make a task wait for a speci fied event to occur The event must be associated with the given semaphore If the semaphore count is greater than zero the call returns immediately and the semaphore count is decremented by one Otherwise the calling task is put into the semaphore waiting list in order of the task priority The task is removed from the waiting list when the semaphore is signalled or when the timeout expires RC_OK if the semaphore was signalled RC_TIME if timed out
13. class KMailBox private K_MBOX m_MailBoxID construction destruction public KMailBox K_MBOX mailboxid access functions public operations public int Send K_PRIO priority K_MSG message int SendW K_PRIO priority K_MSG message int SendWT K_PRIO priority K_MSG message K_TICKS timeout int Receive K_MSG message int ReceiveW K_MSG message int ReceiveWT K_MSG message K_TICKS timeout The constructor takes the mailbox ID number as an argument Other mem ber functions called upon a KMailBox object will result in kernel service calls with the mailbox ID of the mailbox object as the first argument The mapping between member functions and kernel services is the following mailbox Send calls KS_Send MBID mailbox SendW calls KS_SendW MBID mailbox SendWT calls KS_SendWT MBID mailbox Receive calls KS_Receive MBID mailbox ReceiveW calls KS_ReceiveW MBID mailbox ReceiveWT calls KS_ReceiveWT MBID 17 8 KMessage The KMessage class provides a C interface to the K_MSG data structure Because public derivation is used one can still access all members of the K_MSG structure directly A conversion operator to a pointer to a K_MSG is also provided so one can use a KMessage object wherever a pointer to a K_MSG structure is needed The class interface for KMessage is defined as follows Copyright 1996 Eonic Systems
14. include traps inc assume AR5 points to a parameter struct obtain a free packet lat PRHI_GET ldi tar5 FREE_LIST arl nop nop bz list_empty test if call failed use packet pointed to by AR2 SEEALSO PRHI_GETW PRHI_PUT e SPECIAL NOTES This service must not be called from the low priority context TI2 32 Virtuoso Binding Manual Copyright 1996 Eonic Systems Alphabetical List of nanokernel entry points 38 9 BRIEF so eget ce e CLASS 2 Saw es e SYNOPSIS e DESCRIPTION e ENTRY CONDITIONS e EXIT CONDITIONS EXAMPLE SEEALSO e SPECIAL NOTES PRHI_GETW Get next packet from linked list channel or deschedule Process communication LATcond PRHI_GETW PRHI_GETW is defined in TRAPS INC If the channel is not empty the first packet is removed from the linked list and a pointer to it is returned If the channel is empty the calling process is swapped out and set to wait on the channel It will be rescheduled by the next call to the PRHI_PUT service on the same channel AR1 pointer to linked list channel struct AR3 pointer to PCS of calling process AR4 pointer to list element RO AR1 AR2 R11 and ST are corrupted D include traps inc assume AR5 points to a parameter struct A obtain next packet from free_list G lat PRHI_GETW ldi ar5 FREE_LIST arl pointer to free list channel nop nop
15. m request resource and lock and wait with timeout int KS_LockWT K_RES resource K_TICKS ticks Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 17 Virtuoso microkernel services m release resource void KS_Unlock K_RES resource 8 9 Memory management microkernel services a allocate block from a given map void KS_Alloc K_MAP map void block m allocate block from a given map void KS_AllocW K_MAP map void block a allocate block from a given map and wait until available void KS_AllocWT K_MAP map void block K_TICKS ticks m return block to a map given set void KS_Dealloc K_MAP map void block m inquire on blocks in use in Map int KS_InqMap K_MAP map 8 10 Special microkernel services This is a class of directives which are included for special purposes do nothing microkernel service used for benchmarks void KS_Nop void function executed with preemption disabled int KS_User int function void 0 void arg 8 11 Drivers and processor specific services This class of microkernel services is only available for some processors and their use is to enable user tasks to access the processor specific hardware such as communication links and interrupt pins See iface h for the processor specific function P2 18 Virtuoso Reference Manual Copyright 1996 Eonic Systems Virtuoso microkernel services a start a read operation of a block of size bytes
16. 1 An improved NLI file format 2 An improved tracing monitor Copyright 1996 Eonic Systems Virtuoso User Manual INT 3 Release notes V 3 09 1 November 1993 In this release all nanokernel services were implemented as traps This has the benefit that the total interrupt disabling time was reduced and that the nanokernel code can be placed on any memory bank in relation to the pro gram code The manual was largely updated and covers the Virtuoso support packages in a single manual Virtuoso Nano is not yet documented in its VSP imple mentation From this release on every license includes free of charge a binary version of Virtuoso Micro for use with Borland C under DOS permitting an easy cross development at the microkernel level V 3 11 September 1996 This release adds a C API to the microkernel services This reference part of this manual has been extensively revised This version is the first version of Virtuoso to be tested production versions of the Analog Devices 21 06x processor INT 4 Virtuoso User Manual Copyright 1996 Eonic Systems Implementation Specific Features Implementation Specific Features As these manuals are generic not all the software versions will correspond fully with it Some advanced features might be missing or implemented dif ferently depending on the actual target processor Note however that later versions are always supersets of the previous ones unless serious te
17. The second parameter determines the relative priority of the CPU and the DMA engines See filelFACE H for possible options 39 4 Raw link drivers RawLinkDma link prio dma lib Raw communication port driver This provides the KS_Linkin and KS _Link ID LOCATION LBCR GBCR IACK FILE Copyright 1996 Eonic Systems Virtuoso Binding Manual Tl2 49 Predefined drivers 39 5 Task Level Timings Following is a list of task level timings of some of the kernel services pro vided by Virtuoso These timings are the result of timing measurement on a TMS320C40 board with a clock speed of 40MHz and zero wait state pro gram and data memory All timings are in microseconds The C compiler used was TI C v 4 4 Minimum Kernel call Nop 1 9 Message transfer Send Receive with wait Header only 2 59 16 bytes 2 62 128 bytes 2 68 1024 bytes 2 123 ueue operations Enqueue 1 byte 1 AT Dequeue 1 byte 1 17 Enqueue 4 bytes 1 18 Dequeue 4 bytes 1 18 Enqueue Dequeue with wait 2 56 Semaphore operations Signal 1 12 Signal Wait 2 46 Signal WaitTimeout 2 56 Signal WaitMany 2 64 Signal WaitManyTimeout 2 73 Resources Lock or Unlock 1 12 Note that one char is one 32 bit word on the TMS320C40 1 involves no context switch 2 involves two context switches Timing is round trip time TI2 50 Virtuoso Binding Manual Copyright 1996 Eonic System
18. 6 1 Scalable embedded systems Traditional embedded applications are based on a single processors or microcontrollers When the application requires more processing power the designer has two different options 1 Using a more powerful processor 2 Adding processors The same problem arises when he needs to physically redistribute the pro cessing power for technical reasons In both cases with traditional proces sors this will require a hardware redesign and probably a lot of programming work because the underlying hardware has changed The third option is to use from the start on hardware that has interprocessor capabilities be it built in on the chip or with communication hardware at the board level transputers C40 VME The result is that when using Virtuoso P1 46 Virtuoso User Manual Copyright 1996 Eonic Systems Applications from the start on adding additional processing power is a matter of inserting a board while the application only needs to be reconfigured Sysgen then generates the new include files The only thing left to do is to recompile and link the whole program 6 2 Complex control systems Because Virtuoso provides the user with a virtual single processor model it is now much easier to build distributed control systems because it is no longer important where a particular microkernel object is located in the sys tem The programmer will see no logical difference between processing nodes l
19. 7 2 Tasks In areal time application the functions of the system are assigned to various tasks Virtuoso supports as many tasks as the user wants in a single system The nature of each task is of course application dependent and left to the imagination of the system designer However there are attributes The number of tasks is in practice only dependent on the word size of the processor used Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 3 Virtuoso microkernel types amp data structures 7 2 1 7 2 2 7 2 3 that all tasks share These include atask identifier a priority level atask group set atask state an entry point atask abort handler atask stack pointer and stack size atask context ON Oa FP WOOD Task Identifier amp Priority Each task is identified by a numerical identifier which is a number combined with a second field referring to the processor it is located on The task identifier serves as a reference during microkernel operations Virtuoso uses a fixed task numbering scheme where the numbers are generated at compile time because it is low in overhead and quite adequate for most applications Besides an identifier each task also has a priority initially defined at system generation time On each processor the microkernel schedules the local executable tasks in order of priority While the priority is fixed at start time it can be altered by using th
20. Additional benefits from Virtuoso on the transputer As was already indicated the user can still use the normal transputer mech anisms within each priority level We exercise complete control over the transputer from within the Virtuoso kernel As such we are able to provide programming services usually not available for the transputer programmer First of all we are able to monitor each scheduling event so that the pro grammer knows exactly what has happened during the execution of his pro gram In addition we are now in a position to manipulate the execution of the tasks at the instruction level and at the task level This enables us to single step through the user tasks while providing a direct link with the original source code At the time of writing the latter development under the form of a single step debugger was not finished yet Nevertheless the capability of preemptive scheduling provides a lot of real benefits for the transputer programmer First of all the FIFO queue latency is eliminated This means that communication processes now can start as soon as a message arrives on the links The net result is more throughput for short as well as for long messages Secondly the error flag is now task spe cific and the kernel will detect it This simply means more security for the application Thirdly if a link is now disconnected or too noisy so that the nor mal synchronization protocol will result in a hanging communication th
21. It is possible that additional initialisation of registers and or peripheral I O has to be done The best way is to write a C callable procedure that does the necessary additional initialisations and call this procedure before or after the call to KS_EnablelSR Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI2 5 Virtuoso on the ADSP 2106x SHARC 21 6 4 List of ISR related services 1 ENDISR1 Entering the kernel from within an ISR 2 KS_EventW int event Waits for an event at the task level 3 KS_EnablelSR int IRQ void ISR void Installs the ISR 4 KS_DisablelSR int IRQ Disables the ISR See 21 7 The nanokernel on the 21060 on page 7 for more details ADI 2 6 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the ADSP 2106x SHARC 21 7 The nanokernel on the 21060 21 7 1 Introduction The nanokernel provides the lowest level of functionality in the Virtuoso sys tem It is designed to perform extremely fast communication and context switching for a number of processes It also provides the entry points neces sary to integrate interrupt handlers with the rest of the system The price to pay for speed is that the nanokernel processes and interrupt handlers must obey very strict rules regarding to their use of CPU registers and the way they interact with each other From the point of view of the nanokernel an application program consists of a collection of three types
22. KS_ReceiveW MAILBOX1 amp M switch M tx_task case SENDERI put data in MyArray at index given by sender ay M rx_data amp MyArray M info KS_ReceiveData amp M break case SENDER2 allocate space then receive data M rx_data KS_AllocW MAP_2 KS_ReceiveData amp M KS_Dealloc MAP_2 M rx_data break default unknown sender dump message KY M size 0 KS_ReceiveData amp M If a receiving task does not really need a private copy of the message data in order to function correctly it can be written in such a way that a copy is made only if the sender is on a different node The next example shows how this can be achieved As in the previous example the receiver calls KS_ Receive with its data pointer equal to NULL When the call returns the receiver inspects the message to see whether the sending task is on the same node P2 172 Virtuoso Reference Manual Copyright 1996 Eonic Systems Practical hints for correct use If it is the receiver uses the pointer provided by the sender to access the data and reschedules the sender by performing a KS_ReceiveData call with the data size set to zero Otherwise the receiver uses KS_ReceiveData in the normal way to obtain a copy of the data and reschedule the sender Note that it is not necessary to modify the sending task in order to use this method void Receiver K_MS
23. YIELD YIELD is defined in macro h e DESCRIPTION The calling process is swapped out and added to the tail of the process FIFO The process at the head of the FIFO is swapped in This may be the same process if it was the only one ready to execute e ENTRY CONDITIONS i3 pointer to PCS of calling process e EXIT CONDITIONS EXAMPLE This example shows how to avoid a redundant YIELD operation by testing the process FIFO include nanok h include macro h r0 dm NANOK_HEAD r1 0 comp r0 r1 test head of process FIFO if eq jump label YIELD yield if there is another process label e SPECIAL NOTES This service must not be called from the low priority context or by an isr ADI 2 34 Virtuoso Binding Manual Copyright 1996 Eonic Systems Predefined drivers 23 Predefined drivers 23 1 Virtuoso drivers on the 21060 Drivers are the interface between the processor and peripheral hardware and the application program They normally serve two purposes data com munication and synchronization As polling is not a recommended practice in a real time system most drivers will use interrupts in one way or another The Virtuoso system does not provide a standard interface to drivers this allows the application writer to optimize this important part of their implemen tation Some basic services that will be required for almost all drivers are provided Most low level details have
24. 24 BITS PROGRAM CONTROLLER 24x24 56 gt 56 BIT MAC TWO 56 BIT ACCUMULATORS M1 2 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Motorola 56K DSP 27 3 DSP56001 software architecture The programming model indicates that the DSP56001processor architecture can be viewed as three functional units operating in parallel i e the Data ALU the AGU and program controller The goal of the instrucion set is to keep each of the units busy each instruction cycle achieving maximum speed and minimum program size The eight main data ALU registers X0 1 YO 1 A0 1 B0 1 are 24 bits wide The A and B registers have extension registers which are 8 bits wide each When these extensions are used as source operands they occupy the low order portion of the word and the high order portion is sign extended When used as destination operands only the low order portion of the word is received while the high order portion is not used The 24 AGU registers are 16 bits wide and may be accessed as word oper ands for address address modifier and data storage When used as a source operand the registers occupy the low order portion of the word and the high order portion is zero filled When used as destination operand the registers only receive the low order part of the word the high order part is not used The program control registers m the 8 bit OMR Operating Mode Register may be a
25. K_SEMA ADC_SEMA if KS_TestWT ADC_SEMA 10 RC_TIME printf No ADC event in 10 ticks n KS_ Test KS_TestW KS_TestMW KS_TestMWT KS_ Signal KS_SignalM In Virtuoso Micro this service is implemented as a macro Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 111 Alphabetical List of Virtuoso microkernel services 11 73 KS Unlock e SUMMARY Release logical resource e CLASS Resource e SYNOPSIS void KS_Unlock K_RES resource e DESCRIPTION The KS_Unlock microkernel service decrements the lock level of a logical resource If the new lock level is zero the resource is unlocked and available for other users The call is ignored if the calling task is not the owner of the resource e RETURN VALUE NONE EXAMPLE K_RES DATABASE e lt KS_Lock DATABASE grab shared resource Add_Record and update it KS_Unlock DATABASE now release it for other tasks lt e SEE ALSO KS Lock KS_LockW KS_LockWT e SPECIAL NOTES Upon unlocking the resource is allocated to the next task in the priority ordered waiting list P2 112 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services 11 74 e SUMMARY e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE e SPECIAL NOTE KS User Execute function
26. PRHI_WAIT the event has happened PRHI_SIG pointer to signal channel struct pointer to PCS of calling process This service must not be called from the low priority context or by an isr Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 45 Alphabetical List of nanokernel entry points 19 15 PRLO_PSH e BRIEF This call is for internal use only and is not exactly the equivalent of PRHI_PSH for the PRLO process This call assumes that a PRHI process is waiting on the channel and will crash the system if there isn t PRLO_PUSH is used by the K_taskcall function to send command packets from a task to the microkernel process ADI 46 Virtuoso Binding Manual Copyright 1996 Eonic Systems Alphabetical List of nanokernel entry points 19 16 YIELD BRIEF Yield CPU to next nanokernel process e CLASS Process management e SYNOPSIS YIELD YIELD is defined in macro h e DESCRIPTION The calling process is swapped out and added to the tail of the process FIFO The process at the head of the FIFO is swapped in This may be the same process if it was the only one ready to execute e ENTRY CONDITIONS 10 pointer to PCS of calling process e EXIT CONDITIONS rl r2 r0 are corrupted EXAMPLE This example shows how to avoid a redundant YIELD operation by testing the process FIFO include nanok h include macro h i rO dm
27. The host interface driver can be used on two levels The lowest level needs only one kernel resource HOSTRES which secures the use of the low level host interface This kernel resource must always be locked by the task that wants to make use of the host interface and unlocked if this task has fin ished using the host interface A list of low level procedures are at the dis posal of the application programmer to do simple character oriented I O server_putchar server_pollkey server_terminate server_pollesc These procedures will do the locking and unlocking of HOSTRES so that HOSTRES is transparent to the application programmer using the low level host interface Also installed in the examples is an easy to use character oriented I O inter face based on two tasks conidrv and conodrv two queues CONIQ and CONOQ two resources HOSTRES and CONRES and a procedure called print1 This higher level interface driver makes use of the low level inter face procedures It is possible to use an even lower level of the host interface Doing this the application programmer can build other host interfaces that do more than character oriented I O The minimum that is needed to make use of the low est level host interface is the kernel resource HOSTRES to secure the use of the interface and the procedure named call_server Note how ever that HOSTRES is not needed if only one task makes use of the lowest level host i
28. e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO KS _InqMap Returns the number of free blocks in a map Memory management int KS_InqMap K_MAP map The KS_InqMap microkernel service returns the number of free blocks in the memory map Number of free blocks typedef void MyBlock MyBlock p K_MAP MAP3 int FreeBlocks FreeBlocks KS_InqMap MAP3 if FreeBlocks gt 10 KS_AllocW MAP3 amp p KS_Alloc KS_AllocW KS_AllocWT KS_Dealloc Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 51 Alphabetical List of Virtuoso microkernel services 11 23 e SUMMARY e CLASS ey ee e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO KS _ InqQueue Read the current queue depth Queue int KS_InqQueue K_QUEUE queue The KS_InqQueue microkernel service allows the calling task to read the current number of entries in a queue Current number of entries in the queue K_QUEUE CHARQ K_SEMA XOFF int depth depth KS_InqQueue CHARQ if depth gt 20 KS_Signal XOFF KS PurgeQueue P2 52 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services 11 24 e SUMMARY e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO KS _InqSema Read the current semaphore count
29. eeeeeceeeeeeeeeeeeeteeeeeeeeteeeeaaeeneeteaeeee P1 23 Priority and scheduling sai eenetavedoebys sts esteaetegs otcacekadte wares tors cakedeevetteeeiee P1 24 Task execution management cceeceeseeeee ce eeeeeseeeeeeeeeeeeeteeeeeeeeeeeees P1 25 Class TINE Minnir ane Fedele cole ns eevee tect eae Sheds Der eye aa lah tee uel S P1 26 Class MEMON ccctessceeceretecatiots sien silanes E E RS P1 27 Class RESOURCC erinan iaeaea aA ae ae adt ute pteeas ene KESE EE eN P1 29 Class Semaphore sie oo ead ac Reveal na s ee cesesteag deere couantnse dees resten neice P1 29 Class Messag csent nce wall aa a a a A E P1 30 Once only synchronization the KS_MoveData service n s P1 32 AS SCV toca a eas cS cess nc a ade ean cate secie P1 32 ClASS SOCCIA I EE Asse E ak tae ae et ee A E P1 33 Class Processor SPOCIIC ap ater u st saettle aw ccig e i e tere Meee dena P1 33 Low level support with WIUOS Or cascada neces eiaces eerie tod sete aa sesacivees cer ened eee evgu tatty P1 34 Th ISRlevel stice nea ieee beh dae ERARE EE eee P1 35 Levels supported by the Virtuoso products ccccccecceccceceeeceeeeeeeeeeeeeeeeeeeeeeaes P1 37 Support for parallel processing scsccssivesccssescdsnsieeveaden ioc suaveeleveudesteebsategteadnccssnceaten P1 37 Farget EnVironMe nt asez ucini Bite a a aaiae A aT e e aaa ESS P1 37 Virtuoso auxiliary development tOOIS 00 0 ee eee eect teeter eeeeee teen eeeeeeaeeeaeeeeeeeeeneaa
30. tickunit is defined in the MAIN C files This should be used for the unit argument see examples 39 2 Host interface device drivers One of these is required on the ROOT node if the host services are to be used not for booting the network The following are provided void HostLinkDma inlink outlink prio HLDMA LIB DMA based driver for all boards using one or two C40 comports to imple TI2 48 Virtuoso Binding Manual Copyright 1996 Eonic Systems Predefined drivers ment the PC interface The link number to use are a 0 3 for Hema DSP1 m 0 0 for Sang Megalink m 3 3 for Hunt Engineering HEPC2 The prio parameter sets the relative priority of the CPU and the DMA engines when accessing memory Use one of the symbolic constants defined in IFACE H void HLxx_Driver void HLxx LIB xx 03 00 or 33 Interrupt driven PC to comports interface not using DMA You can use one of these in place of HostLinkDma if you want to keep the DMA engines free for other purposes void DPCC40_Driver void DPCC40 LIB Host driver for the LSI DPCC40 board void VmeHostV void HYDRA1 LIB Host driver for the ARIEL HYDRA1 board void SP40Host void SP40 LIB Host driver for the SONITECH SPIRIT40 board 39 3 Netlink drivers Two drivers both using the C40 comports are provided void NetLinkDma link prio NLDMA LIB void Netlink link LINK LIB
31. 20 Virtuoso Reference Manual Copyright 1996 Eonic Systems Nanokernel types and datastructures 9 Nanokernel types and datastructures 9 1 Nanokernel processes and channels The nanokernel unit of execution can be considered as a light task that is a task with a light context as compared with the microkernel tasks To avoid any confusion and in analogy with the internal transputer architecture the following terminology is introduced 1 Processes for designating the nanokernel light tasks 2 Channels for designating the interprocess communication objects The nanokernel has been designed for minimal overhead when switching between processes This has been achieved by 1 A small number of registers that have to be saved over a context switch 2 Aminimum semantic overhead 3 Small size often fitting in internal RAM The small number of registers means that process code must be written in assembly language It is still possible to call C functions from within a process if certain rules are observed The minimum semantic overhead results from the following design options No preemption but interruptible by interrupt service routines Strict FIFO scheduling Only one waiting process allowed when synchronizing with another process No time outs No distributed operation a fF OND These restrictions are not important if the microkernel level is present and if nanokernel processes are used i
32. 33 Class Queue P1 32 Class Resource P1 29 Class Semaphore P1 29 Class Special P1 33 Class Task P1 23 Class Timer P1 26 cleardevice P2 140 clearviewport P2 140 closegraph P2 133 Command packets C40 TI2 18 CompControl M2 3 compilation symbols P1 5 Confidence test P1 4 Customized versions P2 176 D Data types ADI 10 Debugger GLO 1 Debugger commands P2 156 Debugger concepts P2 154 detectgraph P2 132 Developing ISR routines on the 21020 ADI 15 ADI 3 Digital Signal Processors P1 21 Drawing filled forms P2 138 Drawing pixels and lines P2 136 drawpoly P2 137 Driver GLO 1 Driver and mode selection P2 132 Driver description P2 145 Drivers P2 18 DSP 96002 Addressing Modes M3 7 DSP 21020 chip architecture ADI 1 DSP96002 Chip Architecture M3 1 DSP96002 Software Architecture M3 3 E ellipse P2 137 end_isr0 C40 TI2 25 end_isr1 C40 ADI 33 ADI 21 TI2 27 TI2 41 Entry into the debugger P2 154 Event GLO 1 Events C40 TI2 18 execution trace P1 16 Copyright 1996 Eonic Systems IX 1 F fclose P2 128 feof P2 129 ferror P2 129 fflush P2 129 fgetc P2 128 fgetpos P2 129 fgets P2 129 FIFO GLO 1 fileno P2 130 fillellipse P2 138 fillpoly P2 138 floodfill P2 138 fopen P2 128 fprintf P2 130 fputc P2 129 fputs P2 129 fread P2 129 freeimage P2 140 freopen P2 128 fse
33. R6 Stack Pointer R7 Structure Return Address R1 R5 R7 Register promotion by optimiser NO N7 Code Generator Temporary M0 M7 Unused by compiler dangerous side effects A 48 bit function return value float double or long A1 24 bit and 16 bit return value integer or pointer B X Y 48 bit register promotion by optimiser X1 X0 Y1 Y0 24 bit register promotion by optimiser 27 5 3 Subroutine Linkage 27 5 3 1 Preserved Registers Every register in the set performs a specific function thus requiring the pro grammer to preserve any register that is to be directly used in in line and out line assembly language code 27 5 3 2 Register Return Values A 48 bit function return value float double or long Al 24 bit and 16 bit return value integer or pointer 27 5 3 3 Parameter Passing Information passed to C subroutines is stored in a parameter data space which is similar to the local data space However the data is in reverse order and each parameter is referenced via a negative offset from the frame pointer Actual parameters are pushed onto the activation record in reverse order by the calling subroutine see 4 6 1 in G56KCC Motorola DSP56000 DSP56001 Optimizing C Compiler Users Manual 27 5 3 4 Subroutine Call sequence Every time a C language subroutine is called a strict calling convention is fol lowed The subroutine calling sequence is broken down into 3 sub sequences that are strictly defined Copyright 199
34. Virtuoso The Virtual Single Processor Programming System User Manual Covers Virtuoso Micro Virtuoso Classico Version 3 11 Copyright 1996 Eonic Systems Copyright 1996 Eonic Systems Table of Contents Introduction INT 1 Release notes INT 3 V 3 0T September 1992 e a aad ee dette eee INT 3 MSD OS SAMUI Y 1 OID araia cant dete eane e a iner tears a a a Eas INT 3 V 3 09 September 1993 iatons detaches carte dua what ae ese se ecce ae eos te ete INT 3 Wedi09 T Nov mber 1993 oilasi tated nian aneen deed aas aa R pas OECS INT 4 V 3 11 September 1996 cistecs noes dactactaincca qecceates mt cesnuasetisacaneltccteaneeeeatietes Saget INT 4 Implementation Specific Features INT 5 Trademark Notices INT 6 The history of Virtuoso INT 7 POMS EON OS xs ecclesia cuts Sees E A tee sega soe caw ecco sa needs haste nate aclonas Seman see INT 8 Manual Format INT 9 License agreement LIC 1 OWNERSHIP AND CONDITIONS o ecccccecceeeeeeeeeeeeceeeeeeeeeaeecaeee seeeseneaeeseneeeesaees LIC 1 T OWNERSHIP isanne rn atta eet tation hae date Abe LIC 1 2 PEE i sees aeea A EE E Ea Ea a true tebage nadia LIC 1 4 CUSTOMER S PRIVILEGES amp aiuszser seatmeuciiedanenieasmin e a LIC 2 5 CUSTOMER OBLIGATIONS gpreniinnesn a dees Baie ha a LIC 2 6 CUSTOMER PROHIBITIONS sis aeciic baxice teetn easier aren LIC 3 7 IMITED WARRANTY P asses sce a p aee e saine EEEE EESE LIC 4 SB GENERAL a a a E aE
35. Virtuoso on the Motorola 96K DSP M3 30 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Motorola 68HC11 30 Virtuoso on the Motorola 68HC11 Chapter in preparation Copyright 1996 Eonic Systems Virtuoso Binding Manual M4 1 Virtuoso on the Motorola 68HC1 1 M4 2 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Motorola 68HC16 microcontroller 31 Virtuoso on the Motorola 68HC16 microcontroller Chapter in preparation Copyright 1996 Eonic Systems Virtuoso Binding Manual M5 1 Virtuoso on the Motorola 68HC16 microcontroller M5 2 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Mips R3000 systems 32 Virtuoso on the Mips R3000 systems Chapter in preparation Copyright 1996 Eonic Systems Virtuoso Binding Manual R1 1 Virtuoso on the Mips R3000 systems R1 2 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the INMOS T2xx T4xx T8xx 33 Virtuoso on the INMOS T2xx T4xx T8xx 33 1 Introduction This section contains many parts taken from the manual of one of the first real time kernels Eonic Systems developed This provided for the first time preemptive scheduling on the INMOS transputer For this reason this chap ter was more or less kept in its original form and contains the unusual part that explains why one needs a real time kernel on the transputer At that time this was a
36. e RETURN VALUE RC OKif successful RC_TIME if not successful EXAMPLE K_RES GRAPHRES if KS_LockWT GRAPHRES 100 RC_OK moveto 100 100 lineto 200 100 KS_Unlock GRAPHRES else printf cannot lock graphical display n SEEALSO KS_LockW KS_LockWT KS_Unlock KS _ UnlockW KS _UnlockW Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 67 Alphabetical List of Virtuoso microkernel services 11 36 e SUMMARY e CLASS es ey ee SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES KS LowTimer Read the microkernel system timer Timer K_TICKS KS_LowTimer void This call returns the current value in ticks of the microkernel system clock as defined during system generation The current system clock value K_TICKS TimeNow TimeNow KS_LowTimer KS _Elapse KS_HighTimer The precision is processor dependent P2 68 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services 11 37 e SUMMARY e CLASS Saw es e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES KS MoveData Copy data Processor Specific void KS_MoveData int node int size void source void destination int direction Copy size bytes of data from a source address on a source node
37. e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES _init_process Initialize a nanokernel process Process management void _init_process void stack void entry void int ar4 int ar5 This C function initializes the process control structure of a process It must be called before the process is started using start_process The entry point the initial values for AR4 and AR5 and some internal variables are writ ten to the PCS none In this example two processes using the same code but different parameters are initialized and started int adc1 100 stack for first process int adc2 100 stack for second process extern void adc_proc void process code extern struct adc_pars ADC_Params 2 parameter structs _init_process adcl adc_proc amp ADC_Params 0 0 init_process adc2 adc_proc amp ADC_Params 1 0 eee _start_process adcl _start_process adc2 _start_process Copyright 1996 Eonic Systems Virtuoso Binding Manual Tl2 23 Alphabetical List of nanokernel entry points 38 2 _start_process e BRIEF Starts a nanokernel process from the low priority context CLASS Process management e SYNOPSIS void _start_process void stack e DESCRIPTION Starts a nanokernel process by making it executable The process must have been initialized before The process will start exe
38. int size K_TICKS ticks m return the current number of queue entries int KS_InqQueue K_QUEUE queue m remove all current entries and clear the list of the tasks waiting to dequeue voidKS_PurgeQueue K_QUEUE queue 8 7 Timer management microkernel services These services are only available on processors where a timer exists or a periodic interrupt can be supplied to the processor If these functions are not available then the timeout variants ow all waiting kernel functions do also not exist Virtuoso Reference Manual Copyright 1996 Eonic Systems Virtuoso microkernel services m allocate timer K_TIMER KS_AllocTimer void a deallocate timer void KS_DeallocTimer K_TIMER timer Start timer with specified delay or cyclic period and signal semaphore at each period void KS_StartTimer K_TIMER timer K_TICKS delay K_TICKS cyclic_period K_SEMA sema m reset and restart timer with new specified periods void KS_RestartTimer K_TIMER timer K_TICKS delay K_TICKS cyclic_period stop the timer void KS_StopTimer K_Timer timer compute elapsed time K_TICKS KS_Elapse K_TICKS stamp return the low resolution time K_TICKS KS_LowTimer void 8 8 Resource management microkernel services m request resource and lock int KS_Lock K_RES resource m request resource and lock and wait till granted int KS_LockW K_RES resource
39. pointer to channel AR2 data word to push ARO AR1 R11 and ST are corrupted All other registers are preserved include traps inc ref _K_ArgsP microkernel input stack send a command packet to the microkernel assume ar0 points to the command packet lat PRHI_PSH ldi _K_ArgsP arl ldi ar0 ar2 nop PRHI_POP PRHI_POPW This entry point must not by called from the low priority context but it can be used by interrupt handlers Copyright 1996 Eonic Systems Virtuoso Binding Manual TI2 37 Alphabetical List of nanokernel entry points 38 14 PRHI_ SIG e BRIEF Send an event ona signal channel e CLASS Process communication e SYNOPSIS LATcond PRHI_SIG PRHI_SIG is defined in TRAPS INC e DESCRIPTION Ifa process is waiting on the channel it is rescheduled put at the tail of the process FIFO Otherwise the event count is incremented In either case control returns to the caller e ENTRY CONDITIONS AR1 pointer to channel e EXIT CONDITIONS ARO AR1 R11 and ST are corrupted All other registers are preserved EXAMPLE include traps inc assume AR5 points to a parameter struct Signal an event on SYNC_CHAN lat PRHI_SIG ldi ar5 SYNC_CHAN arl nop or other useful instructions nop xecuted before the LAT SEEALSO PRHI_WAIT e SPECIAL NOTES This entry point must not by called from the low priority context but it c
40. the natural way Some people still think parallel programs are hard to write This attitude is understandable if one realizes that older computer technology has more or less dictated the sequential programming style Sequential programming languages reflect the one instruction at a time functional behavior of the older sequential processors Even simple multitasking was a costly function The net result is that most people have been forced for years to squeeze their problem into the constraints of a sequential programming language Most problems however especially in the world of control applications are inherently parallel For example a system will sample external signals pro cess them and then output something to an external device In this generic P1 22 Virtuoso User Manual Copyright 1996 Eonic Systems Functional support from Virtuoso example it is easy to distinguish three functions So what is more natural than to isolate these functions as three tasks The interaction between these tasks is also fairly easy to describe if one defines these interactions as local actions of each of these tasks How much more difficult would this have been using a sequential programming style Nevertheless each task s internal function is probably best described using a sequential notation As such most multitasking and real time kernels have adopted this scheme Virtuoso is no exception to that except that Virtuoso also permits the applic
41. use packet pointed to by AR4 PRHI_GET PRHI_PUT This service must not be called from the low priority context or by an isr Copyright 1996 Eonic Systems Virtuoso Binding Manual TI2 33 Alphabetical List of nanokernel entry points 38 10 PRHI_POP e BRIEF Remove next element from a stack channel e CLASS Process communication e SYNOPSIS LATcond PRHI_POP PRHI_POP is defined in TRAPS INC e DESCRIPTION If the stack is not empty the top element is removed and returned to the caller The Z flag is reset If the stack is empty the Z flag is set and an unde fined value is returned The calling process is never swapped out as a result of calling this service e ENTRY CONDITIONS AR1 pointer to stack channel struct e EXIT CONDITIONS If the stack is not empty ARO and R11 are corrupted AR2 th lement removed from the stack the Z flag is cleared If the stack is empty ARO and R11 are corrupted AR2 undefined the Z flag is set EXAMPLE include traps inc assume AR5 points to a parameter struct obtain top of stack element lat PRHI_POP ldi ar5 INPUT_CHAN arl nop nop bz stack_empty test if call failed use stack element in AR2 SEEALSO PRHI_POPW PRHI_PSH e SPECIAL NOTES This service must not be called from the low priority context TI2 34 Virtuoso Binding Manual Copyright 1996 Eonic Systems Alphabetical List of nanokernel entry point
42. void void void void void stdiodrv void hiqtask void himtask void histask void master void char string 100 char text2 4096 KMessage Message S 60s 5d n ifdef DEBUG static void start_debug K_TASK k KS KS_TaskId _Enqueue DEBUGIN amp k sizeof else static void start_debug endif int size AE Ag E essage rx_task essage tx_data ssage size size KS_Elapse amp t for i 0 i lt 1000 i Mailbox1 Send 1 Message KS_Elapse amp t x ticktime 1000 printf 20d bytes KS_Sleep 250 ANYTASK string Chct S 340d n size K_TASK t Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 193 Microkernel C interface test1 cpp void benchm void K_TICKS et essage rx_task essage tx_data 0 essage size puts KS_Sleep 250 HimTask Start KS_Sleep 100 KS_Elapse amp et for i 0 Mailbox1 SendW et KS_Elapse et ticktime et 1000 printf KS_Sleep 250 message_test 8 message_test KS for Elapse amp et 1 0 et KS_Elapse et ticktime et 1000 printf FORMAT KS_Sleep 250 HiqTask Start KS_Elapse amp et for i 0 et KS_Elapse et ticktime et 1000 printf FORMAT task et i lt 1000 i lt 1000 Demoqx1Queue Enque
43. 1 ms N the number of pro cesses in the low priority queue and TSCH being the time interval to the next descheduling point 2 3 9 The net result is that the transputer FIFO T8 2 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the INMOS T2xx T4xx T8xx TABLE 1 scheduler enables fast throughput but results in unpredictable interrupt ser vice response intervals This problem has been identified by various authors See 8 4 10 In addition even if we were able to start a task upon demand we are still faced with the problem of timely execution Indeed once a critical higher priority task has started we need to be sure that it will run until completion In figure 2 this problem is made explicit by graphically rep resenting two instances of the process queue Table 1 represents typical lower and upper limits of the interrupt service response interval ISRI in microseconds when 5 respectively 10 processes are in the FIFO queue For TSCH it was assumed that a normal distribution was valid with an upper bound of 100 microseconds These figures are to be compared with the results obtained when using Virtuoso A second problem concerns the timely termination of a interrupt service request Even if the programmer were able to start up a critical process within a known and suf ficiently short interval the time slicing mechanism will intervene to allow the other processes to continue Without Virtuoso
44. 2 Terminal type I O is now a separate library 3 The compile and development cycle has been shortened by streamlining the makefiles and library decomposition 4 The KS_Alloc kernel service was modified to allow deallocation when a task is aborted 5 Anew universal network loader We made a lot of efforts to support even better DSP applications In particu lar 1 The ISR structure has been reviewed permitting to eliminate most of the interrupt disabling times 2 Light context tasks were introduced These are used internally by the kernel but can be defined and programmed as well by the user V 3 05 January 1993 The major novelty is the introduction of the nanokernel for the distributed ver sion This consists of several light context tasks and enables very fast inter rupt servicing Following enhancements were added 1 The router will use multiple paths if possible 2 Anew service the KS_MoveData was introduced 3 The transputer and C40 version can be used transparently on mixed net works 4 Introduction of an Application Development Support Package consisting of a Vector Matrix and Fiter library separate product V 3 09 September 1993 The major change is the updating of the manual documenting the nanoker nel For the single processor versions the same hostserver and netloader is being used as with the multiprocessor versions to improve the portability of the applications Following changes were made
45. 39 ADI 26 TI2 33 prhi_pop C40 ADI 40 ADI 27 TI2 34 prhi_popw C40 ADI 41 ADI 28 TI2 35 prhi_psh C40 ADI 43 ADI 30 TI2 37 prhi_put C40 ADI 42 ADI 29 TI2 36 prhi_sig C40 ADI 44 ADI 31 TI2 38 prhi_wait C40 ADI 45 ADI 32 TI2 39 printf P2 130 printl P2 127 Priority GLO 2 Priority and scheduling P1 24 prlo_psh C40 ADI 46 ADI 33 TI2 40 Process GLO 3 Processes P1 14 processor specific services P2 18 Program memory Data memory interface control registers ADI 9 putimage P2 140 putpixel P2 136 puts P2 129 Q Queue GLO 3 Queue definitions P2 150 Queue services P2 15 Queues P2 8 R Read or write graphics parameters and con text P2 134 rectangle P2 136 release notes September 1992 INT 3 rename P2 130 Resource GLO 3 Resource definitions P2 150 Resource management P2 17 Resources P2 8 IX 4 Copyright 1996 Eonic Systems restorecrtmode P2 133 routing tables P2 148 Runtime Environment ADI 10 Runtime header interrupt table ADI 12 Runtime libraries P2 128 S savescreen P2 133 sector P2 138 Semaphore GLO 3 Semaphore definitions P2 150 Semaphore services P2 13 Semaphores P2 5 server_exit P2 125 server_getarg P2 125 server_getenv P2 125 server_pollesc P2 126 server_pollkey P2 126 server_putchar P2 125 P2 126 server_system P2 126
46. Before the call the C compiler processes the parameters according to C con ventions In particular the first two arguments are placed in registers DO and D1 and the remaining argument is placed on the stack After the entry code or prologue in the assembly routine is executed the stack configuration is as shown below Y memory X memory lower addresses Parameter n negative offsets from the Parameter n Frame Pointer Parameter 3 Parameter 3 Return Address lt Frame Pointer gt old Frame Pointer Local Variables positive offsets from the Local Variables Frame Pointer Register saves Register saves lt Memory Stack Pointer gt higher addresses FIGURE 20 Stack usage M3 14 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Motorola 96K DSP 29 6 Interrupt Service Routines ISR The two ISR levels that are normally supported by Virtuoso ISRO and ISR1 are not present in the version for the DSP96002 processor since the DSP96002 supports multiple interrupt levels on its own For more details on the different interrupts supported by the DSP96002 see section 29 3 4 of this manual or even more in detail the DSP96002 User s Guide from Motor ola 29 6 1 ISR conventions When using self written ISRs in conjunction with the Virtuoso kernel there are certain conventions to follow m Registers that must be preserved in a
47. For smaller systems using homogenous types of processors and communication media the current solution is more than adequate P1 48 Virtuoso User Manual Copyright 1996 Eonic Systems Virtuoso w The Virtual Single Processor Programming System User Manual Covers Virtuoso Classico Virtuoso Micro Version 3 11 PART 2 Reference Manual Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 Creation date February 5 1990 Modification date September 6 1996 P2 2 Virtuoso Reference Manual Copyright 1996 Eonic Systems Virtuoso microkernel types amp data structures 7 Virtuoso microkernel types amp data structures 7 1 Microkernel types In order to understand how Virtuoso works and how to build real time application systems around it it is useful although not necessary to understand how its various control and data structures work This section describes these structures and their relationships The descriptions will include Object Type Related C datatypes Tasks K_TASK K_TGROUP K_PRIO Semaphores K_SEMA Mailboxes K_MBOX Queues K_QUEUE Memory Maps K_MAP Resources K_RES Timers K_TICKS The second field in the list above is the predefined corresponding data type The Virtuoso microkernel services which deal with these classes of control and data structures will be presented in a subsequent section See also the k_struct h and k_types h file for the full details
48. Forgets saved blocks and releases the DOS memory they use cleardevice void clearviewport void These calls are supposed to fill the entire screen or the current view port with the current background color There seems to be some prob lems at least in the EGA VGA driver with these calls and the best thing is to avoid using them An alternative way to clear part of the screen is to plot a solid rectangle bar getarccoords struct arccoords arc Returns the actual start and end coordinates used for plotting circle or ellipse based objects e g arc pieslice etc P2 140 Virtuoso Reference Manual Copyright 1996 Eonic Systems System Configuration 14 System Configuration 14 1 System configuration concepts Central to the concept of Virtuoso is the use of a system generation tool that provides two basic functions to the designer Firstly it provides a means to change the system configuration without the need to change the application program by regenerating all the necessary system files automatically Sec ondly it generates all necessary tables and code to initialize the application The system generation tool enables the user to write topology independent code so that when processors are added or removed and kernel objects such as tasks queues etc are moved or their attributes changed the application source code does not need modification To define a Virtuoso system configuration a system d
49. K_QUEUE queueid access functions public K_QUEUE GetID operations public int Enqueue void data int size int EnqueueW void data int size int EnqueueWT void data int size K_TICKS timeout int Dequeue void data int size int DequeueW void data int size void data int size K_TICKS timeout int DequeueWl void Purge int NumberOfEntries The constructor takes the queue ID number as an argument Other member functions called upon a KQueue object will result in kernel service calls with the queue ID of the queue object as the first parameter The mapping between member functions and kernel services is the following queue Enqueue calls KS_Enqueue QID queue EnqueueW calls KS_EnqueueW QID queue EnqueueWT calls KS_EnqueueWT QID queue Dequeue calls KS_Dequeue QID queue DequeueW calls KS_DequeueW QID queue DequeueWT calls KS_DequeueWT QID queue Purge calls KS_PurgeQueue QID queue NumberOfEntries calls KS_InqQueue QID 17 10 KMemoryMap Objects representing kernel memory maps are of the class type KMemory Map The class definition is as follows Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 185 Microkernel C interface 17 11 class KMemoryMap private K_MAP m_MemMapID construction destruction public KMemor
50. LIBS virtosd lib DD dDEBUG DI P DEBUG J o II and put the other definition in comment VIRTLIB LIBS virtos lib whereby is the comment sign There are also two define statements in the mainx c file that the customer can change in order to personalize the debugger only implemented in VIR TUOSO CLASSICO define MONITSIZE 1024 number of monitor records define MONITMASK MONALL MONEVENT defines the quantity of information Then remake the application just by doing MAKE lt Enter gt ADI 52 Virtuoso Binding Manual Copyright 1996 Eonic Systems Predefined drivers LINKF ILE list of the object versions of all source files to be linked along YOUR SOURCE FILES In the examples this is just test c After you have done make ing your application you can run the application by typing gt 21khost rlsi test Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 53 Predefined drivers ADI 54 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the ADSP 2106x SHARC 21 Virtuoso on the ADSP 2106x SHARC 21 1 Virtuoso implementations on the 21060 At this moment both VIRTUOSO MICRO SP and VIRTUOSO CLASSICO VSP exist for the ADSP 2106x The former only includes a microkernel while the latter uses both a microkernel
51. Three steps are required to create a process create a stack for the process a _ initialize the PCS start the process The stack can be placed anywhere in memory It can be a C array of inte gers a memory block allocated by malloc or or even KS _Alloc or a pointer to the start of a named section TI2 10 Virtuoso Binding Manual Copyright 1996 Eonic Systems Programming the nanokernel The function_init_process stack entry ar4 ar5 is used to initial ize the PCS It writes the following values to the first 8 words of the stack 0 PR_LINK 0 link pointer 1 PR_SSTP stack 7 saved stack pointer 2 PR _PAR3 0 saved AR not used for PRHI 3 PR_PAR4 ar4 initial saved value of AR4 4 PR _PAR5 ar5 initial saved value of AR5 5 PR_BITS 0 flags not used for PRHI 6 PR_PEND NANOK_TRMP pointer to terminate code 7 PR_PRUN entry pointer to entry point Calling _start_process stack starts the process As the caller is the PRLO process there can be no other PRHI processes and the new process will start execution immediately Control returns to the caller when the new pro cess terminates or deschedules by waiting on a channel The first time a PRHI process is swapped in it continues from its entry point The stack pointer will point to the PR_PEND field in the PCS SP stack 6 A process terminates by returning to the address in this field The code at NANOK_TRMP invokes the nanokernel swapper t
52. Virtuoso on the Motorola 96K DSP 128 bytes 2 68 1024 bytes 2 123 Queue operations Engueue 1 byte 1 7 Dequeue 1 byte 1 1 7 Enqueue 4 bytes 1 18 Dequeue 4 bytes 1 18 Enqueue Dequeue with wait 2 56 Semaphore operations Signal 1 12 Signal Wait 2 46 Signal WaitTimeout 2 56 Signal WaitMany 2 64 Signal WaitManyTimeout 2 73 Resources Lock or Unlock 1 12 Note One byte is one 32 bit word on the DSP96002 1 involves no context switch 2 involves two context switches Timing is round trip time 29 17 Application development hints The easiest way to start is to copy and modify one of the supplied examples Some of the necessary files have fixed names so each application should be put in a separate directory The following files will be needed for each application SYSDEF The VIRTUOSO system definition file The SYSGEN utility will read this file and generate NODE1 C and NODE1 H MAIN1 C This contains some more configuration options and the C main function Copy from one of the examples A number of configuration options are defined in this file so they can be changed without requiring recompilation of all sources this would be neces Copyright 1996 Eonic Systems Virtuoso Binding Manual M3 27 Virtuoso on the Motorola 96K DSP sary if SYSDEF is modified CLCKFREQ this should be defined to be the clock fre
53. Within each Virtuoso task it is however perfectly save to start up new threads using thread_start The other thread functions thread_priority thread_restart thread_stop are allowed Equivalent Virtuoso functions are provided c Channel I O to threads which are not generated from the same master task For external links use KS_LinkinW and KS_LinkoutW For reading the event pin use KS_EventW For intertask communication you can use mes sage calls d Semaphore functions within threads which are not generated from the same master task For intertask synchronization you can use the Virtuoso semaphore functions All standard file I O routines like printf scanf etc In some cases this will work but the use of it is not advised Use the supplied I O library functions instead Specific routines of the INMOS C Toolset not to be used by the tasks a Timer functions which can cause a descheduling operation ProcTimerAlt ProcTimerAltList ProcAfter T8 12 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the INMOS T2xx T4xx T8xx ProcWait Equivalent Virtuoso functions are provided b Thread functions interfering with Virtuoso ProcReschedule ProcRunHigh ProcPriPar ProcAlloc ProcAllocClean Within each Virtuoso task it is however perfectly save to start up new threads although no tasks should be started up in the transp
54. _init_process adcl 100 adc_proc amp ADC_Params 0 0 init_process adc2 100 adc_proc amp ADC_Params 1 0 eee _start_process adcl _start_process adc2 _start_process Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 31 Alphabetical List of nanokernel entry points 19 2 _start_process e BRIEF Starts a nanokernel process from the low priority context CLASS Process management e SYNOPSIS void _start_process void stack e DESCRIPTION Starts a nanokernel process by making it executable The process must have been initialized before The process will start executing immediately This call returns when the started process deschedules or terminates e RETURN VALUE none EXAMPLE int wsp1 100 int wsp2 100 extern void procl void extern void proc2 void int N 1000 _init_process wspl 100 procl 0 N _init_process wsp2 100 proc2 0 N _start_process wspl _start_process wsp2 SEEALSO _init_process e SPECIAL NOTES This function cannot be used from within a high priority nanokernel process It must be called from the C main function or by a microkernel task only ADI 32 Virtuoso Binding Manual Copyright 1996 Eonic Systems Alphabetical List of nanokernel entry points 19 3 ENDISR1 BRIEF Terminates an ISR and conditionally invokes the process swapper CLASS 20 Sa aS Interrupt service management e S
55. all PRHI processes must be created and started by the PRLO pro cess Two steps are required to create a process m create a stack for the process a initialise the PCS and start up the process The stack can be placed anywhere in memory It can be a C array of inte gers or a memory block allocated by malloc The function start_process stack stacksize entry i1 i2 is used to initialize the PCS and start the process It writes the following values to the first 8 words of the stack see FIGURE 15 on page 10 PR_LINK 0 link pointer PR_SSTP see figure saved stack pointer PR_PI3 0 saved i3 not used for prhi PR_PI1 i1 initial saved i1 PR_PI2 i2 initial saved i2 PR_MODE1 MODE1 saved MODE1 PR_ASTAT ASTAT saved ASTAT PR_BITS 0 user flags not used for prhi The following 2 words are written at the top of the stack PR_PEND NANOK_TRMP_ pointer to terminate code PR_PRUN entry pointer to entry point After the initialisation start_process starts the process As the caller is the PRLO process there can be no other PRHI process and the new process will start execution immediately Control returns to the caller when the new Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI2 9 Virtuoso on the ADSP 2106x SHARC process terminates or is descheduled by waiting for a channel Process Control Structure A PR PEND PR_PRUN i7 stack pointer PR_BITS PR_ASTAT PR_MODE1 PR PI2 PR Plt PR PI3 PR_SSTP i
56. be restarted by a KS_Start service call Task Entry Point The entry point is the address where the task is to begin execution It corresponds with the address of the C function that implements that task The entry point can be changed at runtime to provide a kind of dynamic tasking Task Abort Handler The task abort handler is an alternative entry point that can be installed at runtime This permits to execute asynchronously but only once application dependent actions when the task has been aborted Task Stack Each task must have a stack for its local workspace The size of each task s stack is dependent on many things such as the maximum depth of nested function calls and the maximum amount of working space needed for temporary variables Task Context The context of a task consists of the information needed to resume execution of the task after it has been descheduled On most processors this information consists of the values held in a subset of the processor s registers at the moment the task was descheduled Semaphores There are several forms that a semaphore may take Virtuoso uses counting semaphores The semaphore starts with a count of zero at the start of the program Whenever the semaphore is signalled using the KS_Signal call the count is incremented by one and the signalling task eventually continues execution Whenever a task waits on a semaphore to be signalled using the KS_Wait call two possible s
57. character oriented I O The minimum that is needed to make use of the low est level host interface is the kernel resource HOSTRES to secure the use of the interface and the procedure named call_server Note how ever that HOSTRES is not needed if only one task makes use of the lowest level host interface and if the Task Level Debugger is not present It is not the intention of this manual to lay out the internals of the host interface and the communication protocol between the host server program and the target board s Please contact Eonic Systems if more information is wanted on this topic For more details on the different levels of the host interface see Host server low level functions and Simple terminal oriented I O in the chapter of Runtime libraries The host interface device driver reserves event signal number 6 for its own use Task Level Timings Following is a list of task level timings of some of the kernel services pro vided by Virtuoso These timings are the result of timing measurement on a DSP96002 board with a clock speed of 33MHz and zero wait state program and data memory All timings are in microseconds The C compiler used for the DSP96002 environment is the Intertools C Compiler v 1 1 from Intermetrics Minimum Kernel call Nop 1 9 Message transfer Send Receive with wait Header only 2 59 16 bytes 2 62 M3 26 Virtuoso Binding Manual Copyright 1996 Eonic Systems
58. const void ptr size_t size size_t nmembs FILE stream int fgetpos FILE stream fpos_t pos int fsetpos FILE stream const fpos_t pos int feof FILE stream int ferror FILE stream int fflush FILE stream Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 129 Runtime libraries int fseek FILE stream long int offset int origin long ftell FILE stream void setvbuf FILE stream char buf int mode size_t size int rename const char old const char new int unlink const char name aru int fileno FIE stream fstat int filedesc struct stat info stat const char name struct stat info define getc fgetc define define define putchar c fputc c stdout e e putc fputc getchar getc stdin define rewind f fseek f 0 SEEK_SET define setbuf f b setvbuf f b _IOFBF BUFSIZ define remove f unlink f int fprintf FILE F const char format int vfprintf FILE F const char format va_list vargs int printf const char format int vprintf const char format va_list vargs int sprintf char s const char format P2 130 Virtuoso Referen
59. lt Enter gt LINKF ILE List of the object versions of all source files to be linked along YOUR SOURCE FILES In the examples this is just test c M1 28 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Motorola 68030 systems 28 Virtuoso on the Motorola 68030 systems Virtuoso has been ported to a 68030 based system of CompControl hosted by OS 9 The operation is similar except that common memory regions are used to communicate between the different processor boards This document file contains additional information concerning the Virtuoso kernel 28 1 Source files of the Virtuoso kernel The source files of the Virtuoso kernel are compiled with the GNU C com piler Following source files have to be present in order to be able to make the relocatables a files kernel a mbint2 a starter2 a timerl a C files charconv c condrv c dllist c event c hint c iface c mail c mmap c nodeinit c printf c printl c queue c res c rtxcmain c signal c task c ticks c tldebug c tlmonit c tstdio c h files dilist h iface h k_struct h k_types h siotags h stdarg h tlmonit h tstate h tstdio h makefiles Virtuoso mak Virtuoso_d mak listfiles relocs lst relsdbg 1lst Two makefiles are present Each of them makes relocatables from the source files Virtuoso mak builds relocatables for a version without the Vir tuoso task level debugger Virtuoso_d mak bui
60. pri ority ordered waiting list is kept of all tasks waiting on the semaphore Copyright 1996 Eonic Systems Virtuoso User Manual P1 29 Functional support from Virtuoso Semaphore Level Incremented KS_ Wait KS_ Signal KS_ Signal Semaphore Level Decremented Semaphore Level 0 All semaphore signals consumed FIGURE 7 Semaphore level transition diagram 4 7 7 Class Message Messages are used between a sender and a receiver task This is done using a mailbox The mailbox is used as an intermediate agent that accepts message headers Message headers only contain the necessary information about the actual message This permits to match send and receive of a sender receiver pair In the single processor RTXC in reality a pointer is passed from sender to receiver task With Virtuoso an actual copy of the data is made This data is not part of the message header but is referenced by it In practice this involves more than one step In a first step the message is transmitted while in a second step the data referenced by it is transmit ted P1 30 Virtuoso User Manual Copyright 1996 Eonic Systems Functional support from Virtuoso KS_ReceiveData Receiver Task1 Mailbox KS Send KS _ Receive Msg_struc_S Msg_struc_R Task Requested Sender Sender Requested Receiver Receiver The mailbox will synchronize sender and
61. r3 r5 r6 r7 r9 r10 r11 r13 r14 r15 mrf iO i1 i2 i3 i5 i8 i9 i10 111 114 i15 m0 m1 m2 m3 m8 m9 m10 m11 mrf mrb mode1 mode2 ustat1 ustat2 Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 23 Virtuoso on the Analog Devices 21020 DSP Cfree rO r1 r2 r4 r8 r12 i4 112 m4 m12 Sysset PCSTKP IRPTL IMASK Nswap r3 r5 r6 r7 r9 r10 r11 r13 r14 r15 i3 i5 i8 i9 110 111 114 115 m0 m1 m2 m3 m8 m9 m10 m11 USTAT1 USTAT2 mrOf mrif mr2f mr0b mrib mr2b MODE2 Intset MODE1 ASTAT rO r1 r2 r4 r8 r12 i4 112 The Csave and Cfree sets are defined by the procedure calling standard of the C compiler Csave is the set of registers that are preserved across a sub routine call if a function uses any of these it must restore the initial value on return Cfree is the set of registers that are freely available to all functions the caller of a subroutine is responsible for preserving them if necessary The definition of these two sets largely determine what the microkernel is expected to do when swapping tasks When a task is swapped out as a result of calling a kernel service which to the task is just a C function only the Csave set need be saved When a task is preempted which means that an interrupt handler has woken up the kernel the Cfree set must be saved as well Actually since most of the microkernel is written in C the Cfree set must be saved be
62. server_terminate P2 125 setactivepage P2 133 setallpalette P2 134 setbkcolor P2 135 setcolor P2 135 setfillstyle P2 135 setgraphmode P2 133 setlinestyle P2 135 setpalette P2 134 setrgbpalette P2 134 settextjustify P2 135 settextstyle P2 135 setusercharsize P2 139 setvbuf P2 130 setviewport P2 134 setvisualpage P2 133 setwritemode P2 135 short overview P1 8 Single processor operation P1 38 size parameters P2 151 Special purpose registers on the ADSP 21020 ADI 5 Special services P2 18 sprintf P2 130 Standard O P2 128 Standard I O functions P2 128 start_process C40 ADI 32 TI2 24 stat P2 130 Status Stack ADI 9 Sticky arithmetic status register STKY ADI 7 Support for parallel processing P1 37 Suspend GLO 3 System Configuration P2 141 system configuration P2 175 System definition GLO 3 system definition file format P2 142 system initialization P2 152 T Target Environment P1 37 Task GLO 3 Task Abort Handler P2 5 Task Context P2 5 Task control services P2 12 Task definitions P2 149 Task Entry Point P2 5 Task execution management P1 25 Task group P2 4 Task Identifier amp Priority P2 4 Task Level Timings ADI 50 ADI 40 Task Stack P2 5 Task State P2 4 Tasks P2 3 tasks P1 15 Text plotting P2 139 textdimensions P2 139 The Architecture file ADI 11 The host
63. systems on a chip In fact a typical high end processor is now a completely self contained computer with CPU memory specialized coprocessors and even network facilities As a result the production cost of computers on a chip has become so low that we can start to use them as components Most P1 18 Virtuoso User Manual Copyright 1996 Eonic Systems Functional support from Virtuoso of the systems that use processors in numbers aim at providing more pro cessing power for a lower cost simply because providing the same process ing power in a single very fast processing unit has reached a technological barrier This barrier is mostly an I O barrier For multiprocessor systems this can be the common bus But even on single processor systems the speed of the processor can be so high that no memory exists so that the processor can operate with zero wait states Today we can also apply computers as components in application areas traditionally dominated by dedicated logic The reason being that in most applications the single chip processors are more than fast enough even if the functionality is provided by means of a program As a result it is now perfectly possible to replace traditional hard ware logic or circuitry by a reprogrammeble processor While this does not provide ultimate performance versus hardware this is more than often offset by the fact that one gains flexibility This shows that while every design tries to optimize the p
64. the calling task When the calling task is aborted by a KS Abort or KS_AbortG call the abort handler function is executed using the task iden tity and priority level of the task that installed it KS_Aborted can be called any number of times each subsequent call overwrites the previously installed handler KS_Aborted NULL removes any installed handler The microkernel removes an abort handler after it has been invoked or when a task terminates normally NONE K_RES DISPLAY void DisplayAbort void free the DISPLAY resource safe if another task owns the display a KS_Unlock DISPLAY void Display void KS_Aborted DisplayAbort KS_Lock DISPLAY do display actions KS_Unlock DISPLAY KS_ Abort KS _AbortG P2 28 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services 11 4 e SUMMARY e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO KS Alloc Allocate a block of memory Memory int KS_Alloc K_MAP map void block The KS_Alloc microkernel service is used to allocate a block of memory from a predefined memory map without waiting RC_OK if a block is available RC_FAIL otherwise typedef void MyBlock MyBlock p K_MAP MAP1K int RetCode RetCode KS_Alloc MAP1K amp p if RetCode RC_OK printf Out of memory n KS_AllocW KS_AllocWT KS_Deallo
65. 2 1 Description requirements for the kernel object types The relative order of the definitions is not important except that all NODEs P2 144 Virtuoso Reference Manual Copyright 1996 Eonic Systems System Configuration should be defined before anything else 14 2 2 Node description Virtuoso nodes are composed of a processor with its local memory and com munications ports They are identified by a symbolic name followed by their type if the distinction is relevant The syntax of a NODE definition is e syntax dea s NODE lt name gt lt type gt name 2 2 ae es The symbolic name e type aaa A processor type e g C40 for TMS320C40 This information is not actually used in this version More parameters may be used in future versions e g the number of task priorities currently fixed at 64 sexample NODE ROOT T8 NODE NODE2 T8 NODE NODE3 C40 NODE NODE4 C40 This describes 4 nodes of which two are TMS320C40 DSPs and two are T800 transputers 14 3 Driver description Drivers are defined with their exact C syntax and parameters as they are intended to be used in the application The syntax of a DRIVER definitions is esyntax DRIVER lt node gt lt driver param1 param2 gt node The symbolic name for the node edriver The C function call for the driver Parameters must be correct for the applica tion at hand The default drivers ar
66. 36 Virtuoso Binding Manual Copyright 1996 Eonic Systems Alphabetical List of nanokernel entry points 19 6 SYNOPSYS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES KS EnablelSR Install an ISR and enable the corresponding interrupt Interrupt service management void KS_EnablelSR int isrnum void isr void This C function is used to install remove or replace an interrupt handler It takes two parameters an interrupt number and a pointer to an ISR The pointer is entered into the interrupt vector table and if it is not zero none extern void _host_irgh void KS_EnableISR 8 _host_irgqh KS_DisablelSR Interrupt numbers are m 0 31 for interrupts enabled in the IRPTL register Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 37 Alphabetical List of nanokernel entry points 19 7 PRHI_GET e BRIEF Remove next packet from linked list channel e CLASS Process communication e SYNOPSIS PRHI_GET PRHI_GET is defined in macro h e DESCRIPTION Ifthe channel is not empty the first packet is removed from the linked list the Z flag is reset and a pointer to the packet is returned If the channel is empty the Z flag is set and a NULL pointer is returned The calling process is never swapped out as a result of calling this service e ENTRY CONDITIONS i4 pointer to linked list channel struct
67. 46 KS_EventW P2 48 KS_Groupld P2 49 KS_HighTimer P2 50 KS_InqMap P2 51 KS_InqQueue P2 52 KS_InqSema P2 53 KS_JoinG P2 54 KS_LeaveG P2 55 KS_Linkin P2 56 KS_LinkinW P2 58 KS_LinkinWT P2 59 KS_Linkout P2 61 KS_LinkoutW P2 63 KS_LinkoutWT P2 64 KS_Lock P2 65 KS_LockW P2 66 KS_LockWT P2 67 KS_LowTimer P2 68 KS_MoveData P2 69 KS_Nodeld P2 72 KS_Nop P2 71 KS_PurgeQueue P2 73 KS_ Receive P2 74 KS_ReceiveData P2 76 KS_ReceiveW P2 78 KS_ReceiveWT P2 79 KS_ResetSema P2 81 KS_ResetSemaM P2 82 KS_RestartTimer P2 83 KS Resume P2 84 KS_ResumeG P2 85 KS_Send P2 86 KS_SendW P2 88 KS_SendWT P2 89 KS_SetEntry P2 91 KS_SetPrio P2 92 KS_SetWlper P2 93 KS_ Signal P2 95 KS_SignalM P2 96 KS_Sleep P2 97 KS_ Start P2 98 KS_StartG P2 99 KS_StartTimer P2 100 KS_StopTimer P2 101 KS_Suspend P2 102 KS_SuspendG P2 103 KS_Taskld P2 104 KS_TaskPrio P2 105 KS_ Test P2 106 P2 114 KS_TestM P2 115 KS_TestMW P2 107 KS_TestMWT P2 108 P2 116 KS_TestW P2 110 KS_TestWT P2 111 P2 118 KS_Unlock P2 112 KS_User P2 113 KS_ Workload P2 119 KS_ Yield P2 120 L Levels supported by the Virtuoso products P1 37 license P1 6 line P2 136 linerel P2 136 lineto P2 136 Link descriptions P2 146 Links GLO 1 Low level support P1 34 Mailbox GLO 2 Mailbox definitions P2 151 Manual Format INT 9 manual f
68. As each task is given a priority the scheduler then executes the task that is runable with the highest priority first The orderly execution of the pro gram is achieved through the interaction mechanisms A major benefit is that the different functions are isolated in tasks while the interaction is also well defined The problems have more to do with erroneous programming of the interactions so that they can eventually block the system called deadlock Deadlock is not a property of the use of a kernel at least it shouldn t be but it is a programmer s error In addition a real time kernel must provide the means handling time based events and the protection of common resources Virtuoso has the right ker nel services for this Nevertheless while Virtuoso is based on a priority based scheduling algorithm we plan to introduce some refinements The first one is the use of priority inheritance This mechanism is useful when several tasks use the same resource The basic algorithm will then tempo rarily assign a higher priority to lower priority tasks when they are blocking a higher priority task from running because they have locked on a resource In order to implement support for earliest deadline scheduling we have opted for a simple scheme that works in conjunction with the priority based sched uling This is achieved through additional kernel services that permit to bind the execution of a task to a given time limit Parallel programming
69. DESCRIPTION The KS_TestMW microkernel service performs the same function as the KS_TestW microkernel service except that it uses a semaphore list This function operates as a logical OR The occurrence of an event associated with any one of the semaphores in the list will cause resumption of the wait ing task e RETURN VALUE Semaphore identifier of the event that occurred EXAMPLE K_SEMA Event K_SEMA isti SWITCHI1 SWITCH2 TIMERA Event KS_TestMW List1l wait for any of 3 events SEEALSO KS_ Test KS_TestWT KS_TestMWT KS_ Signal KS_SignalM e SPECIAL NOTES In the situation where multiple events occur only the first one will be returned The rest will be serviced correctly on subsequent KS_Test M W calls Note that a significant overhead can result when the semaphores reside on remote processors In Virtuoso Micro this service is implemented as a macro Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 107 Alphabetical List of Virtuoso microkernel services 11 70 e SUMMARY e CLASS e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO KS TestMWT Test multiple semaphores with timed out wait Semaphore K_SEMA KS_TestMWT K_SEMA list K_TICKS ticks The KS_TestMWT microkernel service performs the same function as the KS _TestMW microkernel service except tha
70. E E tell Cece ETS P2 166 RESUME n ra r aaa a e AE P2 167 ADOR a ani aia eane ai aa eens bans Canteen ae aE EAEEREN P2 167 Star eaea e aaas r aa EE Ea A AE a e E E Ea P2 167 EXILS TED E BU Gi curser ete etsa tee Cand neti dette a a a P2 167 Exit TLBEBUG eiere nne a steed E AE S P2 167 FIG E A EETA I edad seudedew eaparuunmees wemeatdanaes P2 167 The Workload Monitor ssaiisss ccs cease vada vanhenbe date ranendavedaeenedegecaveeenbarettie aReeesse P2 168 Practical hints for correct use P2 170 Flexible use of the messages ois csce apie eats nigsct nie canteediaee senesced nae eeedenees P2 170 General featureS secerni renra a E ER e ARE denier P2 170 Mallboxe S s sena aeee penera a a aE genieea dead saaneenatatasadeaseten ees P2 171 USING MESSAGES iieii ohe eenia EAA vals eek ees a NAE aa P2 171 On the abuse of semaphores s ssnesseessosersoreesntttrnotettrestertnnettnsr rettere eernerre net P2 174 On using the single processor versions for multiple processors cceeeee P2 174 Hints on system configuration ssatehteeet eset eat eens diet hadeds tatirtealaasiwe eden taed P2 175 Customized versions and projects ec ceceeeeeeeeeeeeeeeeeeeeseaeeeeeeeeeeeeeeseeeeeaeeteaeeees P2 176 Microkernel C interface P2 177 Microkernel C classes i alec cars eietctytavety alan deseadtevar tence aida ltegeeareen eed P2 177 Kernel object generation Dy SyYSgen c cccccceecesseeeseeeceeeeeeeeseeee eeceeeeeee
71. Fasmsub That is the compiler prepends an upper case letter F to each C procedure name Therefore the assembly lan guage must define a global symbol of this name that is XDEF Fasmsub Fasmsub lt entry code prologue gt lt body of routine gt lt exit code epilogue gt When a subroutine is called a new copy of the so called subroutine activation record is put on the run time stack and returning from the subroutine removes the activation record An activation record is the run time represen tation of a C subroutine Typically such a record consists of the following ele ments Parameter data space Information passed to C subroutines is stored in a parameter data space which is similar to the local data space Copyright 1996 Eonic Systems Virtuoso Binding Manual M1 13 Virtuoso on the Motorola 56K DSP 27 6 27 6 1 However the data is in reverse order and each parameter is refer enced via a negative offset from the nframe pointer Actual parame ters are pushed onto the activation record in reverse order by the calling subroutine Old frame pointer The old frame pointer provides a dynamic link to the calling subroutine s activation record Once the called subroutine has completed execution the frame pointer will be updated with this value m Return address which is pushed on the DSP s system stack high register This is the return address to the calling subroutine The return address i
72. Hence a minimum interrupt latency as well as interrupt disabling time is a must As an example consider the TMS320C40 DSP This processor requires to handle already up to 14 interrupts sources without any of them being related to external hardware The Virtuoso programming system solves this Gordian Knot by providing an open multilevel system built around a very fast nanokernel managing a num ber of processes The user can program his critical code at the level he needs to achieve the desired performance while keeping the benefits of the other levels Internally the kernel manages the processor context as a resource only swapping and restoring the minimum of registers that is needed The different levels are described below ISR stands for Interrupt Service Routine LEVEL 1 ISRO level This level normally only accepts interrupts from the hardware Interrupts need only be disabled during ISRO e g less than 1 microsecond on a C40 The developer can handle the interrupt completely at this level if required or pass it on to one of the higher levels The latter is the recommended method as it disables global interrupts for a much shorter time This approach allows to handle interrupts in burstmode at over 1 Million interrupts per sec on a C40 The programmer himself is responsible for saving and restoring the context on the stack of the interrupted task Copyright 1996 Eonic Systems Virtuoso User Manual P1 13 Virtuoso an overview
73. KS_LinklnW All other events 0 31 are reserved for the kernel 48 timer event rest 32 63 except 48 are free All event numbers used by the kernel and reserved for the kernel are defined in event h 2 All other values pushed onto the microkernel input channel are interpreted Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 2 15 Virtuoso on the ADSP 2106x SHARC as a pointer to a command packet Command packets are the primary form of communication used within the Virtuoso system They are used by the tasks to request microkernel services sent across the Virtuoso network to implement remote kernel calls and put on waiting lists to represent a task that is waiting for something It is outside the scope of this manual to present a complete description of the command packet data format The basic struc tures and the command codes are defined in K_STRUCT H The microkernel maintains a list of free command packets implemented as a list based channel A pointer to this channel is exported in the C variable K_ArgsFreeP Other PRHI processes can get command packets from this pool but they must never wait for the channel i e always use PRHI_GET If the list is empty correct behavior is to call YIELD and try again later In the Virtuoso network the Srce field of a command packet identifies the sending node and it is used as a return path for reply messages The same field also has a secondary function since al
74. LIBS virtosdr lib DD dDEBUG DDD P DEBUG and put the other definition in comment VIRTLIB LIBS virtosr lib whereby is the comment sign There are also two define statements in the mainx c file that the customer can change in order to personalise the debugger define MONITSIZE 1024 number of monitor records define MONITMASK MONALL MONEVENT what will be monitored Then remake the application just by doing MAKE lt Enter gt LINKFILE list of the object versions of all source files to be linked in the exe cutables After you have done make ing your application you can run the application by typing gt 21khost rlsi test Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 2 43 Application development hints ADI 2 44 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Intel 80x86 26 Virtuoso on the Intel 80x86 26 1 Notes over PC interrupt drivers ISR_C C code that installs the ISR s Interrupt Service Routines coded in the ISR_A ASM file ISR_A ASM code for the interrupt routines that handle the DOS timer Virtuoso takes over the 18 2 Hz timer from DOS it effectively doesn t run anymore and upscales it to 1000 Hz for internal use For some purposes DOS however needs this timer e g when you use the floppy disk inside Vir tuoso the disk spinning motor would run forever because the time out value is never reac
75. LIMITED WARRANTY NO WARRANTY OF THE LICENSED PRODUCT IS PROVIDED EXCEPT AS STIPULATED HEREIN 7 1 Eonic Systems provides the Licensed Product As Is without any war ranty expressed or implied including but not limited to any warranty of mer chantability or fitness for a particular purpose 7 2 Eonic Systems does not warrant that the functions contained in the Licensed Product will meet Customer s requirements or that the operation of the Licensed Product will be uninterrupted or error free 7 3 Eonic Systems does warrant the media upon which the Licensed Prod uct is distributed to Customer to be free of defects in material and workman ship under normal use for a period of ninety 90 days from the date of shipment of the Licensed Product to Customer Eonic Systems will replace such defective media upon its return to Eonic Systems 7 4 Eonic Systems liability hereunder for damages regardless of the form of action shall not exceed the amount paid by Customer for the Licensed Prod uct Eonic Systems will not be liable for any lost profits or for any claims or demands against Customer Eonic Systems shall not be liable for any dam ages caused by delay in delivery installation or furnishing of the Licensed Product under this Agreement In no event will Eonic Systems be liable for any kind of incidental or consequential indirect or special damages of any kind 8 GENERAL 8 1 This Agreement is valid from the moment Cu
76. Local Reject Infinity Negative Zero Overflow Carry M3 6 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Motorola 96K DSP 29 3 1 DSP 96002 addressing modes The DSP96002 instruction set contains a full set of operand addressing modes All address calculations are performed in the Address Generation Unit to minimize execution time and loop overhead Address register indirect modes require an offset and a modifier register for use in address calculations These registers are implied by the address reg ister specified in an effective address in the instruction word Each offset reg ister Nn and each modifier register Mn is assigned to an address register Rn having the same register number n The addressing modes are grouped into three categories m Register Direct Address Register Indirect a PC Relative and Special The Register Direct addressing modes are Data or Control Register Direct a Address Register Direct The Address Register Indirect modes are No Update Rn Postincrement by 1 Rn Postdecrement by 1 Rn Postincrement by Offset Nn Rn Nn Postdecrement by Offset Nn Rn Nn Indexed by Offset Nn Rn Nn Predecrement by 1 Rn Long Displacement Rn Label The PC Relative modes are m Long Displacement PC Relative a Short Displacement PC Relative m Address Register PC Relative Special Addressing modes are a Immediate Data Immediate
77. NANOK_HEAD rl 0 comp r0 r1 test head of process FIFO if eq jump label YIELD yield if there is another process label e SPECIAL NOTES This service must not be called from the low priority context or by an isr Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 47 Predefined drivers 20 Predefined drivers Two devices drivers are already added to this release of the Virtuoso kernel They are a the timer device driver a the host interface device driver acommunication driver based on shared memory present in VIR TUOS CLASSICO VSP The timer device driver is needed for time out features of some kernel ser vices and for kernel timer services The host interface device driver is written to be able to communicate between the host server program and the target board The shared memory driver was especially written for IXTHOS 21020 boards The IXD 7232 was provided with two 21020 processors that can communicate using shared memory This driver can be extended for other types of communication 20 0 1 The timer device driver The timer driver is already installed and enabled in procedure main of the examples that accompany the release of the Virtuoso kernel If the timer ISR is installed and enabled the application programmer can read out the timer in high and in low resolution The two procedures to read out the timer value are m KS_HighTimer m KS _LowTimer In high res
78. SYSVEC __iiof2_isr is installed and enabled SEEALSO KS _EnablelSR KS_DisablelSR e SPECIAL NOTES This entry point is for assembly language programming only The KS _EnablelSR and KS_DisablelSR services use this trap and are C call Copyright 1996 Eonic Systems Virtuoso Binding Manual TI2 45 Alphabetical List of nanokernel entry points able e SPECIAL NOTES Interrupt numbers are m 0 31 for interrupts enabled in the IIE register m 32 35 for IIOFO IIOF3 TI2 46 Virtuoso Binding Manual Copyright 1996 Eonic Systems Alphabetical List of nanokernel entry points 38 21 YIELD BRIEF Yield CPU to next nanokernel process e CLASS Process management e SYNOPSIS LATcond YIELD YIELD is defined in TRAPS INC e DESCRIPTION The calling process is swapped out and added to the tail of the process FIFO The process at the head of the FIFO is swapped in This may be the same process if it was the only one ready to execute e ENTRY CONDITIONS AR3 pointer to PCS of calling process e EXIT CONDITIONS ARO AR1 AR2 R11 and ST are corrupted EXAMPLE This example shows how to avoid a redundant YIELD operation by testing the process FIFO include nanok inc include traps inc f ldi NANOK_HEAD r11 test head of process FIFO nop avoid possible silicon bug latnz YIELD yield if there is another process nop 3 nops or useful
79. Second example as an example for an ISR that does enter the kernel here is the host interrupt service routine used in Virtuoso Classico VSP for SHARC include lt def21060 h gt include macro h macro s for nanokernel include event h segment pm seg_pmco global _rxhost_irgh ADI 2 4 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the ADSP 2106x SHARC endseg segment dm seg_dmda extern _K_ArgsP channel for the kernel endseg segment pm seg_pmco _rxhost_irqh begin registers that MUST be saved by the IRQ dm i7 m7 MODE1 dm i7 m7 ASTAT dm i7 m7 10 dm i7 m7 r dm i7 m7 12 dm i7 m7 r4 dm i7 m7 r8 dm i7 m7 r12 r4 i4 dm i7 m7 r4 dm i7 m7 i12 end registers that MUST be saved by the IRQ 14 dm _K_ArgsP r2 HOST_EVENT PRHI_PSH pushes event on kernel channel ENDISR1 ends the interrupt routine transfers control to nanokernel endseg 21 6 3 Installing an ISR routine Installing an ISR requires a call to KS_EnablelSR The arguments to this function are the IRQ number as defined in IMASK and a pointer to the func tion which is to serve as the ISR ISRs can be installed and enabled in any part of the code of the application To keep a good overview however it is preferable to install enable them ina central place like a master task or in the main function
80. Semaphore int KS_InqSema K_SEMA sema The KS_InqSema microkernel service allows the calling task to read the cur rent count of the specified semaphore It gives the difference between the number of times a semaphore was signalled and the number of times a task was waiting on that semaphore Current semaphore count K_SEMA TestSema int count count KS_IngSema TestSema if count gt 200 printf Consumer tasks can t follow events n KS_ResetSema KS_ResetSemaM Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 53 Alphabetical List of Virtuoso microkernel services 11 25 SUMMARY e CLASS ey ea e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES KS JoinG Add the calling task to the specified task groups Task void KS_JoinG K_TGROUP This microkernel service sets the task group bits in the task group identifier NONE K_TGROUP ALARM_GRP K_TGROUP ABORT_GRP KS_JoinG ALARM_GRP ABORT_GRP KS_JoinG KS _LeaveG This service is currently implemented as a macro and cannot cause a task switch P2 54 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services 11 26 e SUMMARY e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO SEEALSO KS LeaveG Remove the calling task from the specif
81. Systems Virtuoso on the Motorola 56K DSP There are two sorts of ISRs that can be written 1 ISRs that stand on their own and do not make use of the kernel to give signals 2 ISRs giving signals to the kernel In both cases the Stack Pointer R6 must first be incremented prior to sav ing any register at the start of an ISR This is because a critical section exists in the epilogue code of a procedure move R6 move y R6 lt reg gt This instruction sequence restores a previously saved register If an interrupt occurs in between these two instructions the Stack Pointer points to the address where the value of the preserved register is written and the first move in the ISR to save a register will overwrite that value if no prior incre ment of R6 is done The same goes for the preservation of SSH Keeping this potential danger in mind the following prologue code must be used for an ISR of the first class no kernel interaction move R6 prior increment of the SP move lt reg gt y R6 repeat this instruction for every register that must be saved At the end of the ISR right before the RTI instruction following epilogue code must be used move R6 move y R6 lt reg gt repeat this instruction for every register that is saved in the prologue code of the ISR Note that this epilogue code is not critical anymore provided the prologue of all ISRs start with
82. TRANS RTXC was redesigned much more with portability in mind and re named as RTXC MP It was available for targets ranging from 8 bit microcontrollers to 32 bit multi processor networks A major addition to the supported target processors was the Texas Instru ments TMS320C30 and C40 This brought RTXC MP into the DSP world and to a new level of performance However the requirements of DSP appli cations needed a radical new approach in the implementation of the kernel On the one hand DSP applications running on hundreds of processors require a powerful and easily understood paradigm for distributed process ing while on the other hand the need to process interrupts from many sources requires an efficient low level approach Often these apparently conflicting requirements are present in the same system The result of these considerations was Virtuoso The concepts behind Vir tuoso are some of the most advanced and they combine to give very power ful and efficient support for real time DSP and parallel system design The ability to use any of the kernel services to access a kernel object located on another processor in the system no matter where it is located frees the programmer from considering the details of interprocessor communication Because the semantics of the kernel services were designed for distributed operation it is the only system that guarantees that the deterministic behav ior of the application is unchanged when the
83. Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Motorola 56K DSP 27 3 1 Addressing Modes The DSP56K provides three different addressing modes m Register Direct Address Register Indirect Special Register Direct a Data or Control Register Direct Address Register Direct Address Register Indirect No Update Rn Postincrement by 1 Rn Postdecrement by 1 Rn m Postincrement by Offset Nn Rn Nn Postdecrement by Offset Nn Rn Nn m Indexed by Offset Nn Rn Nn m Predecrement by 1 Rn Special Addressing Immediate Data Absolute Address Immediate Short Short Jump Address Absolute Short I O Short Implicit Reference The DSP56K address ALU supports linear modulo and reverse carry arith metic types for all address register indirect modes These arithmetic types easily allow the creation of data structures in memory for FIFOs delay lines circular buffers stacks and bit reversed FFT buffers Each address register Rn has its own modifier register Mn associated with it The contents of this modifier register determines the type of arithmetic to be performed for addressing mode calculations The following modifier classes are supported a Linear Modifier Modulo Modifier m Reverse Carry Modifier Copyright 1996 Eonic Systems Virtuoso Binding Manual M1 5 Virtuoso on the Motorola 56K DSP 27 3 2 27 3 2 1 27 3 2 2 1 0 Memory The on chip peripheral regi
84. Virtuoso Reference Manual P2 183 Microkernel C interface 17 9 class KMessage public K_MSG private construction destruction public KMessage KMessage K_MSG message access functions public INT32 GetSize const INT32 GetInfo const KTask RequestedSender const KTask RequestedReceiver const conversion operators public operator K_MSG operations public void ReceiveData Most of the operators are defined as const and do not allow any changes to be made to the data members of the K_MSG class If they have to be changed one must use the data members of the K_MSG class directly An extra functionality is also that the KMessage class creates and returns KTask objects with the task IDs as defined in the K_MSG struct The correspon dence between the access function of the KMessage class and the data members of the K_MSG struct are as follows message GetSize corresponds to msg size message GetInfo corresponds to msg info message RequestedSender corresponds to msg tx_task message RequestedReceiver corresponds to msg rx_task KQueue Objects representing kernel queues are of the class type KQueue The class definition is as follows P2 184 Virtuoso Reference Manual Copyright 1996 Eonic Systems Microkernel C interface class KQueue private K_QUEUE m_QueueID construction destruction public KQueue
85. When developing a multitasking application on a single processor the pro grammer is free to program his tasks anyway he wants as long as he follows the semantics of the microkernel services When the target is a multiproces sor system and he wants to benefit from the transparent migration of tasks and other Virtuoso objects from one processor to another he has to keep in mind that this imposes one important rule not to use global pointers or glo bal data unless he explicitly wants to exploit the performance of local access using pointers The reason is that otherwise the program code is no longer transparent to the location in the processor network because pointers are local objects by definition By the same token memory allocation is a local operation as well Note that when using local pointers the program might require additional synchronization or resource locking to assure the validity of the data The lat ter requirements are also valid for systems with common memory The resource management services of Virtuoso can be used to implement this protection Let s illustrate this with a small example Two tasks communicate using a mailbox When both tasks are on the same processor it is possible not to send the whole data from the sender to the receiver task but only a pointer to it Provided the user takes the necessary precautions to avoid that the data is overwritten by the sender before the receiver has effectively used it this c
86. a A E ea Raines LIC 4 Part 1 The concepts P1 1 Installation P1 3 Installing th SoftWare sic ces aivoceskethand ccedan a a a ERE E P1 3 Kernel libraries provided a5 22 csi 22 taint naatee ee saodersnanedguen ieananbe ebay Seatenm nunne seee neetna P1 4 CONUGENCOIOST E E Sek ie te eee ate aad ee E P1 4 Virtuoso compilation symbols ceecsewrsesanttesasac tt sacedsaattocemenrssald aetna Cease titatagreae ete P1 5 The license agreement a estas sock onate ti eaattsreea inl easetaese aeactecatel ache ceuman eernate ceearant P1 6 Site developers license ANd runtimes 0 0 eeeeceeeeeceeeceeeeee eeeeeeeeteeeeeneee teases P1 6 Support ANd MAINTENANCE 00a eee ee cece sete teer cee ceaeeteaaaaeee eae aeenseeeeaeseeaaeeeeeeaas P1 6 Cross development Capability eee ecesceeceeeeneeeceeeeaeeeceeesaeeeceeeneeeseeenneeeeeennas P1 6 Thetinalreferente pics eat tas e reed dinar tare a E R a e sue uate P1 7 A short introduction P1 8 TAS ONG PAGS MANUAL aniren a aa sole a aa a eera enas P1 8 Underlying assumptions when programming c cee ceeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeenenaes P1 9 Virtuoso an overview P1 10 Requirements for a programming System cceeeeeeeeeeee eee eeneeeeeeeetaeeteateaeeeseeeaees P1 10 Copyright 1996 Eonic Systems Virtuoso User Manual TOC 1 The high level view a portable set Of services 0 0 0 eee ceeeeeeeeceeeeeeeeteeeeeeentneeeee P1 10 A multi tasking real time microkernel as t
87. already been described in the previous sections on interrupt handling and communication with the microkernel At the higher level a typical driver can usually be divided into three functional parts 1 The first component is a function to install the driver This should initialize the hardware and any data structures used and install interrupt handlers for the driver A call to this function is usually placed inside a driver statement in the system definition file The SYSGEN utility copies this call into a function named init_drivers it generates in the node c files The init_drivers sub routine is called by kernel_init just before it returns 2 Most drivers will provide one or more subroutines that can be called from the task level and that implement the actual functionality of the driver At some point these functions will call KS_EventW or KS_Wait to make the calling task wait for the completion of the driver action 3 One or more interrupt handlers are required to generate the events or sig nals waited for by these subroutines In the simplest case the only actions required from the ISR will be to service the hardware and to reschedule a waiting task and all data handling and protocol implementation can be done at the task level This method can be used if the interrupt frequency is not too high lt 1000HZz For higher data rates some of the task code should be moved to the ISR in order to reduce the number of tas
88. an increment of the Stack Pointer R6 Which registers have to be preserved by an ISR depends on the class of ISR an on which registers are used in the ISR If the ISR stands on its own no signal is made to the kernel only those registers must be preserved that are used by the ISR In this case the prologue and epilogue code just described are to be used In the case the ISR gives a signal to the kernel all registers that are used by the ISR must be preserved except the registers R1 R2 B and X these registers must always be saved at the start of a signalling ISR regardless if they are used by the ISR or not because the kernel is relying Copyright 1996 Eonic Systems Virtuoso Binding Manual M1 15 Virtuoso on the Motorola 56K DSP on the fact that they are saved The kernel expects in register B1 the event signal number which can range from 0 to 63 inclusive So for a signalling ISR next conventions must be followed a fF Ww N First increment the Stack Pointer R6 Save registers X B R1 and R2 in this sequence Save all other registers used by the ISR Do whatever has to be done body of ISR Restore all registers except R2 R1 B and X Note however that the last register restore may NOT contain a decrement of the Stack Pointer because this decrement would be one too much Load register B1 with the event signal number value 0 63 Jump to label Fkernel_sign_entry to give the signal An e
89. at all times remain the sole and exclusive property of Eonic Systems The Licensed Product the original and any copies thereof in whole or in part and all copyright patent trade secret and other intellectual and proprietary rights therein are owned by and remain the valuable property of Eonic Sys tems Customer further acknowledges that the Licensed Product embodies substantial creative efforts and confidential information ideas and expres sions Neither the Licensed Product nor this Agreement may be assigned sublicensed or otherwise transferred by Customer without prior written con sent from Eonic Systems 2 FEES For and in consideration of the rights and privileges granted herein Cus tomer shall pay to Eonic Systems a license fee due and payable upon exe cution of this Agreement in the amount specified on the invoice 3 DEFINITIONS 3 1 SOURCE CODE is any representation of the Licensed Product that is suitable for input to or is produced as output from an assembler compiler interpreter source translator or disassembler either directly or indirectly on any medium regardless of type including but not limited to listings printed on paper and any magnetic or optical medium 3 2 EXECUTABLE CODE is any representation of the Licensed Product which can be directly executed by the instruction set of a computer or indi rectly by an interpreter in a computer The storage or transmission medium is not relevant to this
90. at microkernel level Special int KS_User int function void void ArgList The KS_User microkernel service is used to execute a user function at the priority level of the microkernel All microkernel service requests from ISR s other nodes or the timer system will be queued until the user function returns The user function should be short and must not issue any microker nel service calls Practically speaking during the execution a preemption of tasks is disabled The return value of the function struct arg MyArgs extern int MyFunction MyArgs result KS_User MyFunction amp MyArgs The second parameter to the user function should be a pointer to a structure containing any parameters the function needs Needless to say grave disor der will result if the caller and the routine do not agree on the structure lay out This service cannot be used to run a the function on a remote node Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 113 Alphabetical List of Virtuoso microkernel services 11 75 e SUMMARY e CLASS es ey eae e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES KS Wait Wait on a semaphore Semaphore int KS_Wait K_SEMA sema The KS_Wait microkernel service is used to test whether a specified event has occurred The event must be associated with the given semaphore If the semaph
91. be given pn before triggering the target board the server will pause for n seconds AXXXXXXXx Specifies the absolute address at which the application will be loaded xxxxxxxx is the address in hexadecimal format If this parameter is not given a default absolute address will be taken 08003000 The server can be interrupted or stopped by entering C or E When one does this the server will prompt x to exit c to continue so that the operator can still change his mind here If after all the server is stopped it can always be restarted to resume its duties with the option c Copyright 1996 Eonic Systems Virtuoso Binding Manual M2 11 Virtuoso on the Motorola 68030 systems M2 12 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Motorola 96K DSP 29 Virtuoso on the Motorola 96K DSP 29 1 Virtuoso versions on 96K At this moment two versions exist for the 96K Both contain the microkernel The first one is dedicated to single processor systems and does not contain the nanokernel level This is the version described The second version contains the nanokernel and is suited for multiprocessor targets as well with fully distributed semantics The section on this version is under preparation 29 2 DSP 96002 chip architecture This section contains a brief description of the DSP9600x processor archi tecture It is not intended to be a replacement of the Processor s User Man ual
92. because the length of an Eonic Systems proprietary proto col message is given in the first word of the message itself Therefore a read out of such a message has to be done in two steps After reading out the last piece of the message kernel service KS_FreeMailbox must be called in order to reset an internal read pointer to an initial value This service will also unlock the mailbox so that a new mes sage can be entered in the mailbox So KS FreeMailbox must not be for M2 8 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Motorola 68030 systems gotten nodeinit c This module contains part of the initialization sequence of the system It will correct all pointers within the block of initialized data Because the execut able of an application is built from relocatables initialized pointers will not have an absolute address value A correction factor must be added to the pointers The correction factor is not equal for all initialized pointers For pointers to data structures the global data pointer must be added for pointers to func tions and to constant strings the application start address must be added Both correction factors are calculated by the start routine in module starter2 a and are called GlobDataPtr and StartOfCode Constant strings however can always be used without the need to add a correction factor as these strings are incorporated into the modules them sel
93. but as a quick lookup for the application programmer Detailed information can be found in the DSP96002 User s Manual from Motorola The DSP96002 has a Harvard architecture separated program and data addressing with multiple internal buses The interface to the outside world is done via two programmable ports The concept of the processor family to which this processor belongs defines as its core a Data ALU Address Gen eration Unit AGU Program Controller and associated Instruction Set The On Chip Program Memory Data Memories and Peripherals support many numerically intensive applications however they are not considered part of the core The DSP96002 supports IEEE 754 Single Precision 8 bit Exponent and 24 bit Mantissa and Single Extended Precision 11 bit Exponent and 32 bit Mantissa Floating Point and 32 bit signed and unsigned fixed point arith metic coupled with two identical external memory expansion ports The major components of the DSP96002 are Data Buses and Address Buses Data ALU Address Generation Unit AGU X Data Memory Y Data Memory Program Control and System Stack Program Memory Port A and Port B External Bus Interfaces Copyright 1996 Eonic Systems Virtuoso Binding Manual M3 1 Virtuoso on the Motorola 96K DSP a Internal Bus Switch and Bit Manipulation Unit a I O Interfaces FIGURE 16 does not give all details of the DSP96002 Block Diagram See figure 3 1 in the DSP96002 User
94. by spaces or tabs Comment lines as first printing character can be freely inserted All NLI file can have different sections But not all boards require the same set to be defined in the NLI file Host interface definition lt INTERFACE_TYPE gt lt lIO_ ADDRESS gt Examples LINKCO12 150 HEMA TA1 transputer link interface MEGALINK 200 Sang Megalink EPC2 300 Hunt Engineering HEPC2 ay P2 122 Virtuoso Reference Manual Copyright 1996 Eonic Systems Hostserver and netloader 12 2 2 List of boards Example TYPE ID IOB_O IOB_1 DPRAM CTRL CONF DPCC40 B1 300 0 D400 0800 0000 DPCC40 B2 340 0 0000 0 0 TYPE keyword for board definition ID name for the board IOB_0 PC I O Block 0 address This will be required for all boards I0B_1 PC I O Block 1 address Required if you use DB40 EXE DPRAM This is the SEGMENT address of the Dual Port Ram on the PC side This is required on the root node only CTRL Value written to the Control Register after reset CONF Value written to the Config Register after reset See the DPCC40 manual for a detailed description of CTRL and CONF 12 2 3 List of nodes Example TYPE ID LOCATION SITE LBCR GBCR IACK FILE TIM40 NODE1 BI TIM40 NODE2 BI ne RI 3deba050 32778010 80000000 testl out EC 3deba050 32778010 80000000 test2 out
95. cause a task switch Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 41 Alphabetical List of Virtuoso microkernel services 11 16 SUMMARY e CLASS ey ea e SYNOPSIS e DESCRIPTION e RETURN VALUE e EXAMPLE SEEALSO e SPECIAL NOTES KS Enqueue Insert entry into a FIFO queue Queue int KS_Enqueue K_QUEUE queue void data int size The KS_Enqueue microkernel service is used to put an entry in a FIFO queue If the queue is not full the data is inserted at the end of the queue and the call returns If the queue is full KS_Dequeue returns with an error code RC_OK if operation succeeds RC_FAIL otherwise typedef struct float X Y POINT POINT next_point K_QUEUE POSITION put X Y coordinates in the POSITION queue if queue is full we don t care s void KS_Enqueue POSITION amp next_point sizeof POINT KS_EnqueueW KS _EnqueueWT KS _Dequeue KS DequeueW KS_DequeueWT The size parameter is the number of 8 bit bytes to be queued It should be equal to the width of the queue which implies enqueueing only one entry at P2 42 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services a time or unpredictable side effects may occur Care needs to be taken when specifying the size parameter on systems where characters are stored one per w
96. e EXIT CONDITIONS If the list is not empty r8 is corrupted r2 pointer to removed list element the Z flag is cleared If the list is empty r8 is corrupted r2 0 the Z flag is set EXAMPLE include macro h i4 dm CHANNEL PRHI_GET SEEALSO PRHI_GETW PRHIL_ PUT e SPECIAL NOTES This service must not be called from the low priority context ADI 38 Virtuoso Binding Manual Copyright 1996 Eonic Systems Alphabetical List of nanokernel entry points 19 8 BRIEF so aces e CLASS 2 Saw es e SYNOPSIS e DESCRIPTION e ENTRY CONDITIONS e EXIT CONDITIONS EXAMPLE SEEALSO e SPECIAL NOTES PRHI_GETW Get next packet from linked list channel or deschedule Process communication PRHI_LGETW PRHI_GETW is defined in macro h If the channel is not empty the first packet is removed from the linked list and a pointer to it is returned If the channel is empty the calling process is swapped out and set to wait on the channel It will be rescheduled by the next call to the PRHI_PUT service on the same channel i4 pointer to linked list channel struct 10 pointer to PCS of calling process r2 pointer to list element r8 rl are corrupted include macro h i4 dm CHANNEL PRHI_GETW PRHI_GET PRHI_PUT This service must not be called from the low priority context or by an isr Copyright 1996 Eonic Systems Virtuoso Bindi
97. e SYNOPSIS e DESCRIPTION e RETURN VALUE e EXAMPLE SEEALSO e SPECIAL NOTES KS DequeueW Get an entry from a FIFO queue with wait Queue int KS_DequeueW K_QUEUE queue void data int size KS DequeueW is used to get an entry from a FIFO queue If the queue is EMPTY the calling task is put into a waiting list in order of its priority If the queue is NOT EMPTY the oldest entry in the queue is removed and returned to the calling task RC_OK int command K_QUEUE COMMANDS int RetCode RetCode KS_DequeueW COMMANDS amp command sizeof int if RetCode RC_OK printf problem reading from queue n KS Dequeue KS _DequeueWT KS _Enqueue KS _EnqueueW KS _EnqueueWT The size parameter is the number of 8 bit bytes to be read It should be equal to the width of the queue which implies dequeueing only one entry at a time or unpredictable side effects may occur Care needs to be taken when specifying the size parameter on systems where characters are stored one per word or where sizeof does not return the number of 8 bit bytes in a type P2 36 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services 11 12 e SUMMARY e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO KS DequeueWT Get an Entry from a FIFO queue with timed out
98. elements when issuing a KS_Send call the data size the pointer to the data possibly undefined if message size is zero the requested receiver task the predefined ANYTASK if any task will do the info field optional kh O N The receiver task will fill in the following elements and issue a KS_Receive call the requested sender the predefined ANYTASK if any task will do the data size the starting address to which the data must be copied the info field optional kh OND The mailbox will then try to match the sender and receiver messages and copy the relevant sender message fields into the message structure of the receiver if a match is found and vice versa The message data will automatically be copied starting at the specified address The copy operation will be limited by the smallest given size should the sizes not match The receiver can also inhibit this automatic data copying by filling in a NULL pointer as the starting address This way the receiver can inspect the message and determine which action to take The copying of the datais then started by invoking the KS_ReceiveData service after filling in the starting address and the size Note that the info field can be used to transmit a one word message If no data copying is necessary and the receiver has used a NULL pointer he still has to reschedule the sender by issuing the KS_ReceiveData service call with a zero size filled in This c
99. file How much you need of each depends on your application but the following guidelines may be followed Timers are used to implement timeouts at most one per task and can also be allocated by a task Acommand packet will be needed for each timer allocated by a task Command packets used for calling a kernel service are allocated on the caller s stack and should not be predefined A multiple wait packet will be needed for each semaphore in a KS_WaitMservice call for as long as it remains waiting MAIN1 C also defines some variables used by the console driver tasks the debugger task and the graphics system These are included automatically if you use the standard names for the required kernel objects Finally the main function is the obvious place to install ISR s This should be done AFTER the kernel_init call Note that at this point interrupts are already enabled so you should disable them while initializing the hardware used by your ISR s use TRAP 0O in assembly or the DISABLE macro in C code KS_EnablelSRO disables interrupts while it is executing and enables them unconditionally on return BOOTLSI OBJ can be copied from the LIB directory It replaces the boot module in the compiler library The processor memory bus configuration is Copyright 1996 Eonic Systems Virtuoso Binding Manual TH 5 Virtuoso on the Texas Instruments TMS320C30 amp C31 also defined in this file MAKEFILE the mak
100. from a given link and return the associated event number int KS_Linkin int link int size void destination a starts a write operation of a block of size bytes to a given link and return the associated event number int KS_Linkout int link int size void source m read a block of size bytes from a given link and wait until done void KS_LinkinW int link int size void destination m read a block of size bytes from a given link and wait until done or time out expires only for T800 and T9000 int KS_LinkinWT int linkin int size void destination K_TICKS ticks writes a block of size bytes to a given link and wait till done void KS_LinkoutW int link int size void source write a block of size bytes to a given link and wait until done or time out expires only on T800 and T9000 int KS_LinkoutWT int linkout int size void source K_TICKS ticks m enable an ISR void EnableISR int IRQ void ISR void Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 19 Virtuoso microkernel services disable interrupt service routine int DisableISR int IRQ m suspend the calling task until an event occurrs void KS_EventW int IRQ m read the current high precision clock int KS_HighTimer void m return the current CPU workload int KS _Workload void m set the measuring interval for the workload monitor void KS_SetWlper K_TICKS period P2
101. hard ware timer used to generate the TICKS time TICKTIME the TICK period in microseconds TICKUNIT the TICK period in CLCKFREQ units TICKFREQ the TICK frequency in Hertz The number of available timers command packets and multiple wait packets are also defined in this file How much you need of each depends on your Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 51 Predefined drivers application but the following guidelines may be followed Timers are used to implement time outs at most one per task and can also be allocated by a task A command packet will be needed for each timer allocated by a task Com mand packets used for calling a kernel service are created on the caller s stack and should not be predefined A multiple wait packet will be needed for each semaphore in a KS_WaitM service call for as long as it remains waiting MAIN1 C also defines some variables used by the console driver tasks the clock system the debugger task and the graphics system These are included automatically if you use the standard names for the required kernel objects XXX ACH specifies architecture fileO MAKEFILE The makefiles supplied in the EXAMPLES directory can easily be modified for your application They also show how to organize things so you can optionally include the task level debugger If you want to include the task level debugger put the corresponding definitions out of comment VIRTLIB
102. has a 24 bit signed magnitude fraction and a 8 bit exponent Operations on double precision numbers are calculated with software emulation type int a fixed point 32 bit two s complement number ADI 10 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Analog Devices 21020 DSP m type complex this type is a numerical C extension to the Standard C A complex number is seen as two float or int numbers Underlying types are C data type representation int 32 bit two s complement number long int 32 bit two s complement number short int 32 bit two s complement number unsigned int 32 bit unsigned magnitude number unsigned long int 32 bit unsigned magnitude number char 32 bit two s complement number unsigned char 32 bit unsigned magnitude number float 32 bit IEEE single precision number double 64 bit IEEE double precision number long double 64 bit IEEE double precision number complex int two 32 bit two s complement numbers complex float two 32 bit IEEE single precision numbers 18 7 2 The Architecture file The architecture file describes the memory configuration This configuration is read by the compiler and the linker to determine the memory specification of the target system For example you may specify the memory size mem ory type and the number of wait states used in the different banks of data and program memory The architecture file uses two directives to handle these memory
103. implement remote kernel calls and put on waiting lists to represent a task that is waiting for something It is outside the scope of this manual to present a complete description of the command packet data format The basic struc tures and the command codes are defined in K_STRUCT H The microkernel maintains a list of free command packets implemented as a list based channel A pointer to this channel is exported in the C variable K_ArgsFreeP Other PRHI processes can get command packets from this pool but they must never wait on the channel i e always use PRHI_GET If the list is empty correct behavior is to call YIELD and try again later In the Virtuoso network the Srce field of a command packet identifies the sending node and it is used as a return path for reply messages The same field also has a secondary function since all packets sent or received through the network are allocated from the K_ArgsFree list they should be deallocated after use The network transmitters always free a packet after it has been sent The microkernel deallocates a packet if the Srce field is not zero Consequently command packets not allocated from the free list must have their Srce field set to zero to prevent deallocation Note we are aware of the fact that this logic is a bit confusing Future ver sions of the microkernel will probably use a separate flag to indicate if a packet was dynamically allocated Interrupt handlers and PRHI processes ca
104. in IMASK ADI 2 24 Virtuoso Binding Manual Copyright 1996 Eonic Systems Alphabetical List of nanokernel entry points 22 6 PRHI_GET BRIEF os Aken Remove next packet from linked list channel CLASS Process communication e SYNOPSIS PRHI_GET PRHI GET is defined in macro h e DESCRIPTION If the channel is not empty the first packet is removed from the linked list the Z flag is reset and a pointer to the packet is returned If the channel is empty the Z flag is set and a NULL pointer is returned The calling process is never swapped out as a result of calling this service e ENTRY CONDITIONS i4 pointer to linked list channel struct e EXIT CONDITIONS 10 r2 r8 i4 ASTAT are corrupted If the list is not empty r2 pointer to removed list element the Z flag is cleared If the list is empty r2 0 the Z flag is set EXAMPLE include macro h i4 dm CHANNEL PRHI_GET SEEALSO PRHI_GETW PRHI_PUT e SPECIAL NOTES This service must not be called from the low priority context Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 2 25 Alphabetical List of nanokernel entry points 22 7 PRHI_GETW e BRIEF Get next packet from linked list channel or deschedule e CLASS Process communication e SYNOPSIS PRHI_LGETW PRHI_GETW is defined in macro h e DESCRIPTION If the channel is not empty the first packet is removed from
105. increment semaphore prhi_wait Wait on semaphore to be signalled 10 4 Stack based services prhi_psh Push data onto as prhi_popw Pop data from stac prhi_pop Same as above but 10 5 Linked list based services prhi_put prhi_getw prhi_get tack k wait if stack empty no waiting Insert at head of linked list Get element from linked list wait if list is empty Same as above but no waiting P2 24 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services 11 e SUMMARY CLASS o gigs ek e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES Alphabetical List of Virtuoso microkernel services In the pages to follow each Virtuoso microkernel service will be shown in alphabetical order Each Virtuoso microkernel service will be given in a standard format Brief summary of the service One of the Virtuoso microkernel service classes of which it is a member The formal C declaration including argument typing A description of what the Virtuoso microkernel service does when invoked and how a desired behavior can be obtained The return values of the Virtuoso microkernel service One or more typical Virtuoso microkernel service uses The examples assume the syntax of C but error handling is ignored except for the service un
106. install remove or replace an interrupt handler It takes two parameters an interrupt number and a pointer to an ISR The pointer is entered into the interrupt vector table and if it is not zero the corre sponding interrupt enable bit is set in the IIE or IIF register If the pointer is NULL the interrupt is disabled none extern void _iiof2_isr void KS_EnableISR 34 _iiof2_isr KS_DisablelSR SYSVEC Interrupt numbers are m 0 31 for interrupts enabled in the IIE register m 32 35 for IIOFO IIOF3 Copyright 1996 Eonic Systems Virtuoso Binding Manual Tl2 31 Alphabetical List of nanokernel entry points 38 8 PRHI_ GET e BRIEF Remove next packet from linked list channel e CLASS Process communication e SYNOPSIS LATcond PRHI_GET PRHI_GET is defined in TRAPS INC e DESCRIPTION Ifthe channel is not empty the first packet is removed from the linked list the Z flag is reset and a pointer to the packet is returned If the channel is empty the Z flag is set and a NULL pointer is returned The calling process is never swapped out as a result of calling this service e ENTRY CONDITIONS AR1 pointer to linked list channel struct e EXIT CONDITIONS If the list is not empty ARO and R11 are corrupted AR2 pointer to removed list element the Z flag is cleared If the list is empty ARO and R11 are corrupted AR2 0 the Z flag is set EXAMPLE
107. instructions nop executed before the yield nop e SPECIAL NOTES This service must not be called from the low priority context or by an isr Copyright 1996 Eonic Systems Virtuoso Binding Manual TI2 47 Predefined drivers 39 Predefined drivers A number of devices drivers are provided as standard with the C40 release of the Virtuoso kernel These are m the timer device drivers a the netlink drivers m the rawlink drivers m the host interface device drivers The default drivers are declared in iface h and must be declared as a DRIVER object in the sysdef file in order to use them 39 1 The timer device drivers void TimerO_Driver unit void Timerl_ Driver unit These drivers create an interface to the C40 on chip timer peripherals One one of them should be installed on each node They provide two services to the kernel 1 The function timer_read returns a 32 bit value incrementing at 1 4 of the CPU clock frequency 10 MHz for a 40 MHz C40 This permits very precise time measurements It is used by the workload monitor by the task level monitor to timestamp events and by the KS_HighTimer service 2 Both drivers also generate EVENT 48 with a period determined by the unit argument This is used internally by the kernel to maintain the TICKS time The TICKS time in turn is used for implementing time outs and by the KS _Elapse KS_LowTime and KS_ Sleep services The variable
108. int patt int thick Sets the line drawing parameters You can select the line thickness a number of standard patterns or a user defined pattern void settextstyle int font int direct int size Sets the text plotting parameters There are five standard fonts sup plied with BGI drivers Font 0 is an 8 by 8 pixel bitmap font The others are line fonts You can also specify the direction of the text and its size void settextjustify int horiz int vert Selects text justifications options for the outtext function void setwritemode int mode Sets writemode for plotting operations This can be overwrite mode 0 or exclusive or mode 1 Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 135 Runtime libraries 13 2 4 void getcurrcoords struct point xy Reads the current graphics position Drawing pixels and lines void putpixel int x int y int color int getpixel void void void void void void int x int y Plots or read pixel moveto int x int y moverel int dx int dy Moves to absolute or relative position lineto int x int y linerel int dx int dy line int x1 int yl int x2 int y2 rectangle int left int top int right int bot P2 136 Virtuoso Reference Manual Copyright 1996 Eonic Systems Runtime libraries void circle int xc int yc int r void arc i
109. interrupt interrupts are enabled from this point process the IIOF3 interrupt lat ENDISR1 terminate the ISR Copyright 1996 Eonic Systems Virtuoso Binding Manual Tl2 41 Alphabetical List of nanokernel entry points pop iie nop nop SEEALSO ENDISR1 r first restore the IIE register TI2 42 Virtuoso Binding Manual Copyright 1996 Eonic Systems Alphabetical List of nanokernel entry points 38 18 SYNOPSYS e DESCRIPTION SYSDIS Disable global interrupts Interrupt service management TRAPcond SYSDIS SYSDIS is defined in TRAPS INC This entry point provides a convenient and safe way to reset the GIE bit in the ST register e ENTRY CONDITIONSnone e EXIT CONDITIONS EXAMPLE SEEALSO e SPECIAL NOTES The GIE bit in ST is reset trap SYSDIS code to run with interrupts disabled trap SYSENA SYSENA SYSVEC This trap can be used inside a C function by using the inline assembly state ment Copyright 1996 Eonic Systems Virtuoso Binding Manual TI2 43 Alphabetical List of nanokernel entry points 38 19 SYSENA e BRIEF Enable global interrupts CLASS Interrupt service management e SYNOPSYS TRAPcond SYSENA SYSENA is defined in TRAPS INC e DESCRIPTION This entry point provides a convenient and safe way to set the GIE bit in the ST register e ENTRY CONDITIONSnone e EXIT COND
110. it wants to preserve across the TI2 14 Virtuoso Binding Manual Copyright 1996 Eonic Systems Programming the nanokernel call If a PRHI process is swapped in as the result of an interrupt handler calling an ENDISR service then the INTSET registers are available to the PRHI process Before calling a C function the process must save the set CFREE INTSET and it must restore the same registers before it is swapped out this is always possible since a PRHI process is never preempted Note that INTSET is a subset of CFREE so the minimal register set that is always available is INTSET NSWAP Also NSWAP is a subset of CSAVE In fact NSWAP and INTSET have the same meaning to the nanokernel level that CSAVE and CFREE have to the C level The two set inclusions men tioned above also mean that the nanokernel is already doing part of the job of swapping microkernel tasks This is of course no coincidence 37 6 Interrupt handling In the Virtuoso system model interrupt handlers are the interface between asynchronous events and the processes that are waiting for them To be use ful most interrupt handlers will have to interact with the rest of the system at some time Using flags to be polled by the foreground process is usually not an acceptable practice in a real time system This method introduces a superloop structure into the application with all its inherent problems In a system using the nanokernel interrup
111. last instruction before the RTS instruction This module also contains a copy routine called fastcopy It copies blocks of memory as fast as possible by copying 4 bytes at a time if the block to be copied is more than 3 bytes long This routine is used several times in the kernel to copy for instance a kernel message body It is a C callable routine so that applications can easily use it too charconv c printf c Because several standard C functions written for the OS 9 environment use OS 9 features some functions used by the application are re written atoi printf The idea behind it is to have the greatest possible independency of OS 9 libraries for an application written to run on Virtuoso on the target processor board condrv c Console input and output is queue driven in Virtuoso Two tasks one for con sole input the other for console output run at a high priority to handle con sole I O Communication with these two tasks is done via a Input resp Output queue If console input output is not needed in the application the console tasks and queues can be removed from the system description files node1 c and node1 h In this case this module is not needed too hint c Kernel service KS_Linkin is serially oriented reading out of the VME mail box message can be done in more than one step by calling KS_Linkin se veral times This is particularly interesting to process the Eonic Systems pro prietary protocol
112. less than three nodes you don t need data packets 4 buffers for each concurrent data transmission will usually be enough ef define NDPACKS 5 number of multiple wait packets iS define NWPACKS 20 See part 3 the Virtuoso Binding Manual for more details Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 153 Debugging environment under Virtuoso 15 Debugging environment under Virtuoso 15 1 15 2 15 2 1 Task level debugger concepts The task level debugger provides snapshots of the Virtuoso object states It can be called from within the program or from the keyboard The debugger operates as a task and is usually set up as the task with the highest priority on the root node On other nodes in the system specific peek poke functions are linked in with the Virtuoso kernel so the debugger task on the root can exam the object states on any node in the system Whenever The debugger runs it freezes the rest of the system thereby permitting coherent views of the Virtuoso kernel objects The debugger is not intended as a replacement for other debugging tools but is meant to assist the user in tuning the perfor mance or checking out problems within the Virtuoso environment The debugger outputs on the screen of the PC or workstation that acts as the host of the target board Some versions also work with a simple charac ter terminal Because the debugger usually operates as the highest
113. lt _stdio h gt include allnodes h void receiver int data KS_DequeueW DEMOQ amp data 4 printf Received d from queue n data Note that the queue is identified in the calls to the kernel services by use of a C symbol with the same name as was used in the sysdef file This is declared in the header file allnodes h These microkernel object identifi ers can be accessed from code running on any node due to the Virtual Sin gle Processor implementation In this example it does not matter on which processor the queue is placed both tasks can access it as if it were on the same processor In the SP or MP versions of Virtuoso the two tasks and the queue would all have to be placed on the same processor The two tasks should be stored in separate files so that when the code is generated for the two nodes each node is only linked with the functions it needs wth no dead code When the program is run the following output should be seen Sending 42 to queue Received 42 from queue Copyright 1996 Eonic Systems Virtuoso User Manual P1 45 Applications 6 Applications Virtuoso makes it much easier to use multiple processors to solve a single problem The result is the feasibility of a new range of applications that were not possible before or not cost efficient Command amp Control FIGURE 13 With Virtuoso processors can easily be added or moved
114. m suspend a set of taskgroups void KS_SuspendG K_TGROUP taskgroup m resume a task void KS_Resume K_TASK task m resume a set of taskgroups void KS_ResumeG K_TGROUP taskgroup m abort a task void KS_Abort K_TASK task m abort a set of taskgroups void KS_AbortG K_TGROUP taskgroup m install an abort handler function void KS_Aborted void function void a delay a task void KS_Sleep K_TICKS ticks a yield processor to another task void KS_Yield void a set timeslicing period void KS_SetSlice K_TICKS ticks K_PRIO prio P2 12 Virtuoso Reference Manual Copyright 1996 Eonic Systems Virtuoso microkernel services a change a task s priority void KS_SetPrio K_TASK task int priority a change a task s entry point void KS_SetEntry K_TASK task void function void m add a task to a set of taskgroups void KS_JoinG K_TGROUP taskgroup m remove a task from a set of taskgroups void KS_LeaveG K_TGROUP taskgroup get current task identifier K_TASK KS_TaskId m get current taskgroup mask K_TGROUP KS_GroupId void get current task s priority K_PRIO KS_TaskPrio m get current task s node identifier K_NODE KS_NodeId 8 4 Semaphore microkernel services A complete set of microkernel services for using counting semaphores is provided by Virtuoso signal semaphore void KS_Signal K_SEMA sema signal multiple semaphores void KS_SignalM K_SEMA se
115. mes sage from a mailbox If a matching message was found the receiver s K_MSG will be updated using information from the sending task s K_MSG If the receiving task has provided a valid destination pointer the message data will be copied automatically the service returns and the sending task is rescheduled Otherwise if the receiver has provided a NULL pointer the copying of the message data is delayed until the receiving task issues a KS _ReceiveData service call When the size given by the sender and receiver differ the copy operation is limited to the smallest size If the send ing task was filled in as ANYTASK the first matching message in the mailbox will be received The KS_Receive call returns with an error if no matching message is available in the mailbox RC_OK if successful RC_FAIL if not successful K_MSG msg char data 256 msg size 256 msg tx_task ANYTASK msg rx_data data if KS_Receive MAIL1 amp msg RC_OK printf Received d bytes from d n msg size msg tx_task else printf No matching message n P2 74 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services SEEALSO KS Send KS_SendW KS_SendWT KS _ ReceiveW KS_ReceiveWT KS_ReceiveData Practical hints section of this manual e SPECIAL NOTES The size member is the number of 8 bit bytes in the message Care needs to be taken when specifying sizes on system
116. model the C compiler explicitly loads the correct value in the DP register whenever a variable is accessed Assembly language programs must do the same In most cases three cycles will be required to access a static data object but the size of bss is not limited to 64 K The Virtuoso system uses the small model for speed Please note that this imposes a 64 K word limit on static data only Data objects accessed via pointers can be of any size 36 2 3 Parameter passing conventions The compiler supports two methods for passing parameters to C subrou Copyright 1996 Eonic Systems Virtuoso Binding Manual Tl2 5 Virtuoso on the Texas Instruments TMS320C40 tines The standard method in C is to push parameters on the stack in reverse order The called function initializes its frame pointer from the stack pointer value at entry and finds the arguments at constant offsets from the frame pointer Using the register parameter model mr option the first few up to six argu ments are passed using a subset of the available registers The exact assignment depends on the types of the arguments and is fully documented in the Compiler Manual Virtuoso uses the register method for optimal performance Mixing both models is normally not possible so all application code must be compiled using the mr option 36 2 4 Memory sections for the C compiler and Virtuoso The following sections are created by the C compiler text prog
117. netload in main 1 c Normally used for single processor targets Options can be separated l s q or combined lsq and may be given in any order Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 121 Hostserver and netloader 12 2 12 2 1 A network file must have the extension NLI You don t have to type it as it will be appended by the host program Note also that in older versions of the software the single processor versions did not take the NLI file but the executable image file as first parameter To facilitate portability we are applying the multiprocessor approach for single as well as the multiprocessor packages even if this means that the node information and the interconnection topology is not used Examples HOST_X lt ENTER gt displays the help messag HOST_X test lt ENTER gt reads and syntax checks the network file test nli HOST_X rlsvv test lt ENTER gt runs the application described in test nli shows full details of booting operations and provides services to application Network file The network file NLI is board and target dependent See the read me files and the examples for the right contents to use with your board We provide here a generic explanation Network NLI files are text files that can be created using a program editor Most of the data is in tabular form with fields separated
118. objects irrespective of the fact that the C object is used or not Although the overhead per object is small it may be too large in those cases where a lot of objects are defined and not much memory is present at all nodes In these cases the user has the possibility to make node specific versions of the vkobjcts cpp file with those objects that are not referenced at a given Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 189 Microkernel C interface a include include include Node nodel h vkobl hpp VKMemMap hpp ROOT KMemoryMap MaplMemorymap MAP1 Sysdef taskname node prio entry stack groups ay Jk Gieohoe Ss Ar iets erin ee eet Beteie aie toe Baia 8 ot os ieee ee TASK STDIODRV ROOT 3 stdiodrv 128 EXE TASK HIQTASK ROOT 4 higqtask 128 TASK HIMTASK ROOT 5 himtask 128 TASK HISTASK ROOT 6 histask 128 TASK MASTER ROOT 7 master 400 EXE queue node depth width a aE a haat pe a al we ac Sa aes Be he QUEUE STDIQ ROOT 64 WORD QUEUE STDOQ ROOT 64 WORD QUEUE DEMOQX1 ROOT 1000 BYTE QUEUE DEMOQX4 ROOT 1000 WORD map node blocks blsize PE ah Sanit enh N Paci abc act te nh at igh ey Pest Nabi Sah hack gh Sie ac Ne a hee ho pect ENNA MAP MAP1 ROOT 4 1K sema node SS a a ee E A x SEMA SEMO ROOT SEMA SEM ROOT SEMA SEM2 ROOT SEMA SEM3 ROOT SEMA SEM4 ROOT mailbox node x EEE AEN E ERN act Side ek oa bury Sk EEE tre pct
119. of execution In Virtuoso a task is a program module which exists to perform a defined function or a set of functions A task is independent of other tasks but may establish relationships with other tasks These relationships may exist in the form of data structures input output or other constructs A task executes when the Virtuoso task scheduler determines that the resources required by the task are available Once it begins running the task has control of all of the needed system s resources But as there are other tasks in the system a running task cannot be allowed to control all of the resources all of the time Copyright 1996 Eonic Systems Virtuoso User Manual P1 23 Functional support from Virtuoso Thus Virtuoso uses the concept of multitasking Multitasking appears to give the processor the apparent ability to be per forming multiple operations concurrently Obviously a processor cannot be doing two or more things at once as it is a sequential machine However with the functions of the system segregated into different tasks the effect of con currency can be achieved In multitasking each task once given operating control either runs to completion or to a point where it must wait for an event to occur for a needed resource to become available or until it is interrupted Efficient use of the processor can be obtained by using the time a task might wait for an event to occur to run another task This switching from on
120. of the developer in a wide range of applications What Virtuoso deliv ers today is the potential to combine the incremental processing from a sin gle processor to over a 1000 multi processor network while meeting hard real time constraints We look forward to receiving your comments opinions and suggestions which might help us in the evolution of Virtuoso As Virtuoso comes with 12 months support and upgrades do not hesitate to contact us It could save you a lot of time and it could start a long lasting relationship Milestones m 1989 ISI founded m 1990 Release of TRANS RTXC a 1992 Virtual Single Processor concept introduced a 1992 RTXC MP ported to the TMS320C30 and C40 m 1992 Release of 2nd generation kernel Virtuoso m 1993 Nanokernel programming level introduced m 1994 Port to ADSP 21020 and 21060 m 1995 Release of Virtuoso Synchro m 1995 ISI changed name to Eonic Systems Inc INT 8 Virtuoso User Manual Copyright 1996 Eonic Systems Manual Format Manual Format This manual set is divided into three distinct parts PART 1 Virtuoso concepts This part discusses the general philosophy behind Virtuoso It gives infor mation on how Virtuoso operates the concepts behind its design and how the developer needs to use it A short tutorial is included in order to prepare the user who is not familiar with real time programming PART 2 Virtuoso Reference Manual This part contains the reference part of the manual w
121. of the system if defined so in the system generation file or at runtime from within another task During its life a task can be suspended i e blocked from running and resumed after wards When suspended the task has no chance to become executable so this service must be used with caution With the KS_SetEntry service one can change the actual function of a task at runtime After a subsequent KS_Start call the task will then have a different function Virtuoso also per mits to group tasks and has services that operate on a whole group within a single call Note especially the microkernel services KS_SetPrio and KS_Yield These enable to change the order of execution in order of prior ity at runtime When tasks happen to have the same priority they are sched uled in a round robin fashion i e they run until they are descheduled or until they yield the CPU voluntarily The user should base his program on any order of execution when assigning equal priority to a number of tasks In addition when a task issues a microkernel service that is not immediately available Virtuoso will put the task in a wait state During the wait state another task can be rescheduled to continue its execution The wait state and suspend state can be coexisting It is very important to know that when several tasks are in a wait state while requesting the same service in con junction with the same microkernel object e g a resource they are inserted
122. only the first one will be returned The rest will be serviced correctly on subsequent KS_Wait M calls Note that a significant overhead can result when the semaphores P2 116 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services reside on remote processors In Virtuoso Classico this service is implemented as a macro Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 117 Alphabetical List of Virtuoso microkernel services 11 78 SUMMARY e CLASS es ey eae e SYNOPSIS e DESCRIPTION e RETURN VALUE e EXAMPLE SEEALSO e SPECIAL NOTES KS WaitT Wait on a semaphore with time out Semaphore int KS_WaitT K_SEMA sema K_TICKS ticks The KS_WaitT microkernel service is used to make a task wait for a speci fied event to occur The event must be associated with the given semaphore If the semaphore count is greater than zero the call returns immediately and the semaphore count is decremented by one Otherwise the calling task is put into the semaphore waiting list in order of the task priority The task is removed from the waiting list when the semaphore is signalled or when the timeout expires RC_OK if the semaphore was signalled RC_TIME if the call timed out K_SEMA ADC_SEMA if KS_WaitT ADC_SEMA 10 RC_TIME printf No ADC event in 10 ticks n KS Wai KS_WaitM KS_Wait
123. or NULL if there is none NANOK_HEAD Head pointer for a linked list of PRHI processes that are ready to run When the current PRLO process is swapped out the PRHI process at the head of the list is removed and becomes the current process NANOK_TAIL Tail pointer for a linked list of PRHI processes that are ready to run When a process becomes ready to execute it is added to the tail of the list NANOK_PRLO Pointer to the PCS of the PRLO process This is a constant as far as the nanokernel is concerned The microkernel modifies this pointer NANOK_CRIT This is the number of interrupt handlers running with global interrupts enabled that are not yet terminated The process swapping is dis abled while this value is not zero On the 21060 this field is not necessary because IMASKP contains all necessary information on the interrupt nesting state Symbolic constants for accessing kernel variables and elements of a PCS are defined in the file nanok h ADI 2 8 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the ADSP 2106x SHARC 21 7 3 Process management The nanokernel variables are initialized as follows NANOK_PRHI 0 NANOK_HEAD 0 NANOK_TAIL amp NANOK_HEAD NANOK_PRLO amp PCS for IDLE process NANOK_CRIT 0 This means that when an application is started the idle process of the nanokernel will start In the current version of the nanokernel in Virtuoso Classico VSP for SHARC
124. or your distributor for a list Not all processors supported by Virtuoso are supported with all possible implementations A choice was made depending on the specific processor architecture as well as on the typical use made of the processor In all cases is the microkernel available offering an identical interface from single 8bit microcontrollers to mixed parallel processing networks of 32bit DSPs and other processors As not all processor versions are fully upgraded to the latest version Refer to the release floppy or the previous manual if there is a inconsistency Eonic Systems is upgrading all versions to be source level compatible as much as possible Eonic Systems International Inc has taken up the challenge to continually improve its product by further streamlining the code by extending the func tionality and the flexibility of the kernel and by adding tools that will support the designer during the development phase as well as during the rest of the life cycle of the applications developed Therefore the current version is sub ject to modification and will be upgraded on a regular base For more information info eonic com For support contact support eonic com WEB page http www eonic com INT 2 Virtuoso User Manual Copyright 1996 Eonic Systems Release notes Release notes V 3 01 September 1992 This version does not contain many changes In particular 1 The I O library was revised and extended
125. passed on the packet to a transmitter driver to forward the packet to another processor 3 5 Processor specific support If a target processor has specific hardware features that enable the program mer to take advantage of most likely Virtuoso provides a set of services that exploit these features E g high precision timers and drivers for communica tion ports See iface h and the binding manual in part 3 for details Copyright 1996 Eonic Systems Virtuoso User Manual P1 17 Functional support from Virtuoso 4 Functional support from Virtuoso 4 1 4 2 Introduction Virtuoso is probably the first programming tool that provides hard real time capabilities to programmers of parallel systems without abandoning the experience one has gained from programming multitasking applications on single processor systems As such Virtuoso comes in two versions The first one is dedicated to single processor targets while the second version pro vides for a transparent distributed operation In conjunction with the associ ated programming tools it is also a tool that provides for easy programming of parallel processing systems in general For these reasons we call Virtuoso the virtual single processor programming system While the runtime library that comes with a compiler only provides for low level services Virtuoso pro vides for a complete programming framework On the other hand Virtuoso is much smaller and faster than a full o
126. programming them to work together is still a major intellectual challenge to be compared with the design of any complex system where different subunits interact What Virtuoso delivers is a tool that helps to meet these challenges in terms of programming such a system That is it was designed to be able to solve hard real time problems This kind of problem is the most difficult and more general case when compared with other systems where the real time requirements are less stringent In order to keep up with the technology Copyright 1996 Eonic Systems Virtuoso User Manual P1 19 Functional support from Virtuoso 4 3 portability was a major issue The use of C is consistent with this objective as today every new processor is released with a decent C compiler even DSPs Finally the problem of parallel and or distributed programming has been solved by the adoption of a virtual single processor model Based on a message passing mechanism this is a very general approach that can be ported to any environment common memory local memory and LANs The result is that Virtuoso provides for portable applications from simple 8bit microcontrollers to systems with a large number of high end 32bit proces sors It is also universal independent of the processor or of the communica tion medium and scalable if more power is needed one adds processors and redistributes the workload What is hard real time Real time systems are inhere
127. real time kernel brings you many advantages compared to the standard operating environment However to support real time operations the user must refrain from using certain runtime functions In general it can be stated that all operations which influence the scheduling should be per formed through the provided kernel functions If the user performs actions such as for example link I O or timer_wait the proper working of the kernel can not be guaranteed It is the users responsibility to assure that the rules below are followed 33 13 Specific Parallel C routines not to be used by the tasks The programmer must not use any 3L call that can activate the hardware scheduler from outside the task s boundary In particular this means any call that directly accesses the links the event pin or the timer Also starting up threads at high priority is not permitted Use the equivalent Virtuoso calls a Timer functions which can cause a descheduling operation timer_delay timer_wait alt_wait Copyright 1996 Eonic Systems Virtuoso Binding Manual T8 11 Virtuoso on the INMOS T2xx T4xx T8xx 33 14 alt_wait_vec The other functions timer_now and timer_after can be freely used Equivalent Virtuoso functions are provided b Thread functions interfering with Virtuoso thread_create Uses par_malloc which is not protected under Virtuoso thread_deschedule Uses the timer functions
128. secures the use of the low level host interface This kernel resource must always be locked by the task that wants to make use of the host interface and unlocked if this task has fin ished using the host interface A list of low level procedures are at the dis posal of the application programmer to do simple character oriented I O server_putch server_pollkey server_terminate server_pollesc These procedures will do the locking and unlocking of HOSTRES so that HOSTRES is transparent to the application programmer using the low level host interface Also installed in the examples is an easy to use character oriented I O inter face based on two tasks conidrv and conodrv two queues CONIQ and CONOQ two resources HOSTRES and CONRES and a procedure called print1 This higher level interface driver makes use of the low level inter face procedures It is possible to use an even lower level of the host interface Doing this the application programmer can build other host interfaces that do more than character oriented I O The minimum that is needed to make use of the low est level host interface is the kernel resource HOSTRES to secure the use of the interface and the procedure named call_server Note how ever that HOSTRES is not needed if only one task makes use of the lowest level host interface and if the Task Level Debugger is not present It is not the intention of this manual to lay out the internals of
129. services Care needs to be taken when specifying the size parameter on systems where characters are stored one per word or where sizeof does not return the number of 8 bit bytes in a type This service is only available on Virtuoso Classico P2 70 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services 11 38 e SUMMARY e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE KS Nop No operation Special void KS_Nop void The KS_Nop microkernel service is included in the microkernel services for completeness It is used as a benchmark for measuring the minimum inter val to enter and exit the microkernel NONE int i K_TICKS timestamp et KS_Elapse amp timestamp for i 0 i 10000 itt KS_Nop 7 i et KS_Elapse amp timestamp printf 10000 NOPs in d ticks n et Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 71 Alphabetical List of Virtuoso microkernel services 11 39 KS Nodeld e SUMMARY Node identifier of the calling task CLASS Task e SYNOPSIS extern K_NODE KS_NodeId e DESCRIPTION The KS_Nodeld microkernel variable provides a means of knowing which node the task resides on e RETURN VALUE The node identifier EXAMPLE K_NODE MyNode KS_Nodeld e SPECIAL NOTES Modifying KS_Nodeld will almost certainly have undes
130. specifications a SEGMENT tells the linker which memory segments may be used BANK specifies the physical memory on the target board The architecture file also uses two other directives which identify your sys tem mw SYSTEM name of your ADSP 21020 system PROCESSOR defines the processor_type 21020 2106x More information about writing and understanding architecture files can be found in the ADSP 21020 Family Assembler Tools and Simulator Manual and in the ADSP 21020 Family C Tools Manual from Analog Devices Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 11 Virtuoso on the Analog Devices 21020 DSP 18 7 3 Runtime header interrupt table A portion of memory is reserved for the interrupt table The interrupt table is where the linker puts the code in the runtime header O20_hdr obj This runtime header is automatically linked in when you invoke the compiler 18 8 Assembly language interface This paragraph shortly shows how to interface assembly language code with C code It gives an overview of the most important things you must keep in mind when you are writing C callable assembly functions There are two registers called the stack pointer and the frame pointer that are used to manipulate the runtime stack i7 points to the top of the stack i6 points to the start of the frame for the current function Register i13 is used by the C calling protocol to contai
131. tasks Waiters W tasks waiting for return of KS_Send W T Waiters R tasks waiting for return of KS_Receive W T Example gt m MAILBOX STATES Name Count Waiters 0 GETPOSM 504 W R BALL2 BALL4 BALL6 BALLS 1 REPORT 508 W R MASTER Network buffers Subject to change Clock Timers This debugger command will list the remaining events on the timer list Four informations are provided Time the remaining time before the timer event will arrive Repeat an eventual periodically scheduled timer interval Action the action to be done when the timer event arrives P2 164 Virtuoso Reference Manual Copyright 1996 Eonic Systems Debugging environment under Virtuoso Object the type of object on which the actions applies The possible actions are TO Xxx Kernel service xxx times out Wakeup KS_Sleep ends Timed Signal Associated semaphore will be signalled SG Time Repeat Action Object 145 Wakeup CONDEMO 15 2 14 Stack Limits This function is intended to assist the user in tuning the use of RAM needed for stack space by tasks as well as by Virtuoso The snapshot consists of four columns Task the task s symbolic name Current the current amount of stack being used Used the maximum amount of stack ever used Size the defined stack size gt k STACK STACKS Task Current Used Size TLDEBUG 45 201 256 CONODRV 16 38 64 C
132. the Analog Devices 21020 DSP include lt def21020 h gt define HOSTSIG 8 defines event number for host segment pm seg_pmco extern _kernel_sign_entry external function global _rxhost_irgh makes it C callable endseg segment pm seg_pmco _rxhost_irgh dm i7 m7 ASTAT dm i7 m7 MODE1 dm i7 m7 r2 dm i7 m7 r4 r4 i4 dm i7 m7 r4 jump _kernel_sign_entry DB r4 HOSTSIG 1 bit CLR MODE1 IRPTEN 2 First ASTAT and MODE1 have to be pushed on the stack This is to make sure that these registers are correctly saved in all cases Which registers have to be preserved by an ISR depends on the class of the ISR and on which registers are used in the ISR If the ISR stands on its own no signal is made to the kernel only those registers must be preserved that are used by the ISR In the case the ISR gives a signal to the kernel all registers that are used by the ISR must be preserved except the registers R2 R4 14 these registers must always be saved at the start of a signalling ISR regardless if they are used by the ISR or not because the kernel is relying on the fact that they are saved The ISR ends with a kernel_sign_entry The kernel expects the event signal number in register R4 In this example the event 8 is sig nalled to the kernel for further processing At that moment interrupts are dis abled Note also the use of
133. the application is such that the block of un initialized data comes first then the block of initialized data follows Therefore the block of initialized data will be moved in a higher address space with the amount of bytes equal to the size of the un initialized data block Then the address space between the application code and the moved block of initialized data will serve as the block of un initialized data This address space is then filled with zeros The start routine is entered via an exception of the VME mailbox memory At the end of the start routine a return from exception or RTE causes the pro cessor to return to its normal processing state This mechanism will now be used to go to the C routine main by overwriting the normal RTE return address with the address of main Further initializations performed by the start routine are 1 initialization of the VME mailbox 2 correction of all the pointer values in the initialized data block see additional information concerning the module nodeinit c mbint2 a The VME mailbox address space is only used as a trigger to initiate a mail box exception The actual mailbox is fixed at address 0x08000100 and has a M2 6 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Motorola 68030 systems maximum length of 64 32 bit words In the mailbox exception routine the exception is translated to a kernel signal signal cod
134. the host interface and the communication protocol between the host server program and the target board s Please contact Eonic Systems if more information is wanted on this topic For more details on the different levels of the host interface see Host server Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 49 Predefined drivers 20 0 3 20 1 low level functions and Simple terminal oriented I O in the chapter of Runtime libraries The host interface device driver reserves event signal number 8 for its own use Shared memory driver This driver was specific written for IXTHOS boards These boards are pro vided with two 21020 processors Each of these processors have their own program and data memory space Beside that there is a pool of shared memory present Both processors can access the shared memory In Virtu oso Classico the shared memory is used for communication The customer can install the driver by adding to the SYSDEF file NETLINK NODE1 MemLink NODE2 MemLink Task Level Timings Following is a list of task level timings of some of the kernel services pro vided by Virtuoso These timings are the result of a timing measurement on a ADSP 21020 board with a clock speed of 25MHz The kernel used for these timings is the VIRTUOSO Microkernel All timings are in microseconds The C compiler used is the G21k C Com piler v 3 0 from Analog Devices Minimum Kernel c
135. the nanokernel interrupt handlers can communicate with processes using the same channel operations that are available to pro cesses However there are some restrictions In contrast to a process an interrupt service routine does not have a private workspace it executes on the stack of whatever process was interrupted An ISR on the 21020 can be interrupted by an ISR of higher priority So any number of interrupt handlers can be piled on top of each other on the same stack owned by the current process This has some important conse quences 1 If an ISR calls a channel service that has a signal action any process swap that results from this call must be delayed until all interrupt han dlers have terminated These implies that only the PRHI_type of channel operations can be used as these do not invoke the swapper for a signal action there is no need to swap as the caller already has the highest priority When the last stacked interrupt terminates the swapper must be called to verify if a swap from the PRLO process to a PRHI process is necessary 2 An ISR must never call any channel service that has a wait action Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 25 Virtuoso on the Analog Devices 21020 DSP 18 10 10 18 10 11 Doing so would also block all other interrupt handlers that are stacked below it as well as the current process Another way of seeing this is that an ISR cannot wait for something bec
136. the process FIFO or invoke the nanokernel swapper All channels have an internal state What exactly is represented by the state depends on the type of the channel typically this will be the occurrence of an event or the availability of data An operation on a channel can consist of any combination of the following action types Wait The process is said to wait for a channel Signal Signalling action This action can reschedule a process Test and modify modifies or tests the state of a channel Three channel types are predefined in the current nanokernel implementa tion in Virtuoso Classico VSP It is possible to create new channel types if necessary an example will be given at the end of this chapter A full descrip tion of the nanokernel services for each of these channel types can be found in the alphabetical list in the next chapter 21 7 5 SEMA_CHAN counting or semaphore channel This is an implementation of a counting semaphore It is typically used by interrupt handlers to reschedule a process that was waiting for the interrupt The C_CHAN structure has two fields CH_PROC pointer to the PCS of the waiting process or NULL CH_NSIG event counter Two nanokernel services are available for this channel type PRHI_WAIT waiting action PRHI_SIG signalling action 21 7 6 LIFO_CHAN List channel This type of channel maintains a linked list of memory blocks using the first word in each block as a link pointer Th
137. to a desti nation address on a destination node as indicated by the direction RECV or SEND and wait until the operation is finished When the direction is RECV receive the node argument is the source node and the destination node is the one on which the receiving task is residing When the direction is SEND transmit the node argument is the destination node and the source node is the one on which the sending task is residing With SEND the service returns when it is safe to overwrite the original data but the return does not indicate the remote termination of the operation With RECV the service returns when all data has been moved to the destination area On a single processor the operation is implemented as a memcpy operation NONE int VideoNode char Imagel 1024 char DisplayMem KS_MoveData VideoNode 1024 amp Imagel DisplayMem SEND iface h This service must be used with care While it provides for the highest da tarates copying to a wrong memory location can have unpredictable results Therefore the task that receives the data must provide the sending task with a valid pointer Note that the user must take account of the data representa tion If the source and destination areas overlap the results of this operation are unpredictable The size parameter is the number of 8 bit bytes to be transferred Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 69 Alphabetical List of Virtuoso microkernel
138. to schedule the application tasks Another point to see is the protocol involved when using the server However in this example it perfectly demonstrates the interrupting nature of the pre emptive scheduler We hope you will enjoy using this product remember our 12 months free support service and we will greatly appreciate your comments or sugges tions for improving this product based on your experience in the field 1 4 Virtuoso compilation symbols When recompiling the Virtuoso kernel you ll have to enable or disable the compile time switches These are as follows Copyright 1996 Eonic Systems Virtuoso User Manual P1 5 Installation 1 5 1 5 1 1 5 2 1 6 TLDEBUG If defined includes support for the task level debugger TLMONIT This switch does include the use of the tracing monitor The default delivered virtosd lib always includes both switches The license agreement Site developers license and runtimes All Virtuoso products contain the same license agreement This license agreement is basically a site developers license that gives you the right to install the software on one developer s stations at the same site The binary version does not contains runtime royalties except those for developing The version with source code also contains runtime royalties for 100 target pro cessors Above this amount contact Eonic Systems or your distributor Support and maintenance Any Virtuos
139. to specify all available comport links a minimal set that con nects all nodes is all that is required The hostprogram will find out the short est path to boot each node P2 124 Virtuoso Reference Manual Copyright 1996 Eonic Systems Hostserver and netloader 12 3 Host server interface The hostserver is accessed from the target using a low level driver This driver establishes a protocol between the server and the target The target always takes the initiative This is done by writing to a memory location called TXDATA using the call_server function The reply from the server can be read in the RXDATA memory location Access to the host as well as to the memory locations must be protected by locking on the HOSTRES resource The host server functionality can easily be extended by the user See the user subdirectory You will need to recompile the host server 12 4 Host interface low level driver These functions permit a direct access to the host server They are intended for the kernel developer and are only available on the root processor void server_echo unsigned c As many entries as indicated by the parameter of the function are trans ferred from the array TXDATA to the host server The host server will then return a copy of that packet to the array RXDATA void server_exit int c define server terminate server_exit 0 This function will terminate the host server The value of its parameter is u
140. tomer and Eonic Systems oral or written relating to the subject matter hereof and constitutes the whole full and complete Agreement between Customer and Eonic Systems 8 5 The Licensed Product includes a 12 months period of support and main tenance provided Customer submits his questions in written form and Cus tomer duly returns the completed form to Eonic Systems that accompanies the Licensed Product Copyright 1996 Eonic Systems Virtuoso User Manual LIC 5 License agreement RETURN A SIGNED COPY TO EONIC SYSTEMS TO VALIDATE THE 12 MONTHS MAINTENANCE IN WITNESS WHEREOF the parties hereto have executed this Agreement by their duly authorized representatives CUSTOMER print Authorized Signature Address print EONIC SYSTEMS Nieuwlandlaan 9 B 3200 Aarschot Belgium Date LIC 6 Virtuoso User Manual Copyright 1996 Eonic Systems License agreement RETURN A SIGNED COPY TO EONIC SYSTEMS TO VALIDATE THE 12 MONTHS MAINTENANCE EXHIBIT A LICENSED PRODUCTS Product Serial Number Qty LICENSED SITE print or type Company Department Address State Prov ZIP Postal Code Country Telephone Fax e mail Technical Contact FOR BONIC SYSTEMS USE ONLY Order Date Invoice Date Shipped Reseller Date Reg Received Copyright 1996 Eo
141. two parameters are passed in DO and D1 and the remaining param eters are pushed on the stack unless the called routine accepts a variable number of arguments In this case the variable length portion of the parame ter list is always pushed on the stack Other parameters are pushed as one word Double parameters are pushed as one word in L memory If the first parame ter is a structure all parameters get pushed on the stack If the first parame ter is not a structure but the second one is the first parameter will be passed in DO and the remaining parameters will be pushed Copyright 1996 Eonic Systems Virtuoso Binding Manual M3 11 Virtuoso on the Motorola 96K DSP Calling Sequence The generated code for a procedure call has the following form 1 Determine if the function return value will be returned in a register If not allocate space for a function return on the stack 2 Load the first two arguments into registers DO and D1 3 Push the remaining arguments onto the stack The arguments are pushed as words in reverse order i e the last argument is pushed first Ifa function return temporary was allocated push its address Call the function Pop off any stack arguments Ifa function return temporary was allocated deallocate it after it is used N oo RA Procedure Prologue and Epilogue No prologue and epilogue code is generated for leaf routines that have no local variables A leaf routine is one
142. type KSemaphore The class definition is as follows Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 181 Microkernel C interface class KSemaphore private K_SEMA m_semaphorelID construction destruction public KSemaphore K_SEMA semaid access functions public K_SEMA GetID int GetCount operations public void Reset void Signal int TestW int TestWT old for compatibility int Wait int WaitT The constructor takes the sempahore ID number as an argument The GetID member function allows to retrieve the ID of a semaphore object Other member functions called upon a KSemaphore object will result in ker nel service calls with the semaphore ID of the semaphore object as the first argument The mapping between member functions and kernel services is the following semaphore GetCount calls KS_IngSema SEMAID semaphore Reset calls KS_Reset Sema SEMAID semaphore Signal calls KS_Signal SEMAID semaphore Testw calls KS_TestW SEMAID semaphore TestWT calls KS_TestWI SEMAID semaphore Wait calls KS_Wait SEMAID semaphore WaitT calls KS WaitT SEMAID 17 7 KMailBox Objects representing kernel mailboxes are of the class type KMailBox The class definition is as follows P2 182 Virtuoso Reference Manual Copyright 1996 Eonic Systems Microkernel C interface
143. using the microkernel API A microkernel clock providing timing information to tasks and services Time outs and elapsed time can be used without declaring a separate timer Timed semaphore signalling one shot or periodic is provided by a timer declared in the system definition file Copyright 1996 Eonic Systems Virtuoso User Manual GLO 3 Yield Virtuoso VSP A task or process voluntarily gives the CPU to other tasks or processes In the microkernel execution will only be passed to tasks of equal priority A family of tools for real time programming Virtual Single Processor A product version that provides the full range of services in a way that is transparently distributed over multiple pro cessors GLO 4 Virtuoso User Manual Copyright 1996 Eonic Systems Index Numerics 21020 relevant documentation ADI 10 ADI 1 96002 relevant documentation M3 10 A Abort GLO 1 abuse of semaphores P2 174 ADSP 21020 addressing modes ADI 4 Alphabetical list of ISR related services ADI 18 ADI 6 Application development hints ADI 51 ADI 42 Applications P1 46 arc P2 137 Arithmetic status register ASTAT ADI 6 Assembly language interface ADI 12 assumptions P1 9 auxiliary development tools P1 37 bar P2 138 bar3d P2 138 C call_server P2 126 circle P2 137 Class GLO 1 Class Memory P1 27 Class Message P1 30 Class processor specific P1
144. vices that operate on channels should be considered part of the nanokernel as they may modify the process FIFO or invoke the nanokernel swapper All channels have an internal state What exactly is represented by the state depends on the type of the channel typically this will be the occurence of an event or the availability of data An operation on a channel can consist of any combination of the following action types Wait The process is said to wait on a channel Signal Signalling action This action can reschedule a process Test and modify modifies or tests the state of a channel Three channel types are predefined in the current nanokernel implementa tion It is possible to create new channel types if necessary an example will be given at the end of this chapter A full description of the nanokernel ser vices for each of these channel types can be found in the alphabetical list in the next chapter 18 10 5 C_CHAN counting channel This is an implementation of a counting semaphore It is typically used by interrupt handlers to reschedule a process that was waiting for the interrupt The C_CHAN structure has two fields CH_PROC pointer to the PCS of the waiting process or NULL CH_NSIG event counter Two nanokernel services are available for this channel type PRHI_WAIT waiting action PRHI_SIG signalling action ADI 22 Virtuoso Binding Manual Copyright 1996 Eonic Syst
145. wait Queue int KS_DequeueWT K_QUEUE queue void data int size K_TICKS ticks KS DequeueWT is used to get an entry from a FIFO queue If the queue is EMPTY the calling task is put into a waiting list in order of its priority until the QUEUE NOT EMPTY condition or until the timeout expires If the queue is NOT EMPTY the oldest entry in the queue is removed and returned to the calling task RC_OK or RC_TIME if the service timed out int command int RetCode K_QUEUE COMMANDS K_SEMA OPERATOR_SLEEPS read a command Retcode KS_DequeueWT COMMANDS amp command sizeof int 100 if RetCode RC_TIME command was not supplied in time KS_Signal OPERATOR_SLEEPS KS _Dequeue KS _DequeueW KS _Enqueue KS_EnqueueW KS_EnqueueWT Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 37 Alphabetical List of Virtuoso microkernel services e SPECIAL NOTES The size parameter is the number of 8 bit bytes to be read It should be equal to the width of the queue which implies dequeueing only one entry at a time or unpredictable side effects may occur Care needs to be taken when specifying the size parameter on systems where characters are stored one per word or where sizeof does not return the number of 8 bit bytes in a type P2 38 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Vi
146. which makes no procedure calls For routines which have local variables packed in registers a move instruc tion will be generated to save the register upon entry and restore it before exiting For all non leaf routines a move must be emitted to save SSH on the stack When local variables exist that couldn t be packed in registers code must be emitted to save and restore the frame pointer R6 and the stack pointer R7 Example of a leaf procedure with all locals packed to registers Prologue move lt reg gt y R7 1 move for each preserved register word Epilogue move R7 2 moves for first preserved register move y R7 lt reg gt note however that if there are any other registers to be restored the decrement of R7 may be coalesced onto the M3 12 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Motorola 96K DSP previous move Example of a leaf procedure with stack labels Prologue move n N7 n is the size of the new frame move R6 xX R7 save FP in X side of stack move R7 R6 set up new FP from SP move R7 N7 update SP to restore space for the new frame move lt reg gt y R7 1 move for each preserved register to be saved Epilogue move R7 moves to restore preserved move y R7 lt reg gt registers move R6 R7 restore old stack pointer move x R6 R6 restore old frame pointer Exampl
147. zero only if it actu ally did save the graphics screen and context In this case it should be matched afterwards by a call to restscreen A zero return value indicates that the call was not necessary already in text mode or that not enough DOS memory was available Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 133 Runtime libraries int graphresult void Returns an error code for the last unsuccesful graphics operation 13 2 3 Read or write graphics parameters and context void getmodepars struct modepars mpars Obtains parameters describing the current graphics mode This can be used to make a program adapt itself to the available hardware and so be more portable See GRINT H for details on the values returned in the modepars structure The pixel aspect ratio parameters describes the relative visual size in X and Y of a pixel This can be used to obtain the same scaling in X and Y void setviewport struct viewport vport Sets the viewport for the following plot actions A viewport is a rect angular part of the screen The origin the point referenced by coordi nates 0 0 is set at the upper left corner of this rectangle If the clip field is not zero all following plot actions are limited to the area deter mined by the viewport void getviewport struct viewport vport Reads the current viewport and clip option void setallpalette struct palette pal Sets t
148. 02 Virtuoso Nano SP is available on the E tools Minikit Documentation is pro vided separately with this product 27 10 Predefined drivers Two devices drivers are already added to this release of the Virtuoso kernel They are m the timer device driver a the host interface device driver Copyright 1996 Eonic Systems Virtuoso Binding Manual M1 23 Virtuoso on the Motorola 56K DSP 27 10 1 27 10 2 The timer device driver is needed for time out features of some kernel ser vices and for kernel timer services The host interface device driver is written to be able to communicate between the host server program and the DSP56000 target board The timer device driver Only the DSP56002 processors with versions from D41G have an internal timer For the older 5600x processors the implementation of the timing func tions depends on what is provided by the boards For example the 56001 LSI board provides a hardware timer which is connected with the IRQB inter rupt line This difference of timer implementation results in a few consequences for the microkernel services as will be explained later in this section The timer driver is always installed and enabled in procedure main by means of the KS_EnablelSR service If the internal timer is used the first parameter of this function is 30 because the timer interrupt vector address is 30 On the other hand if the timer is implemented by means of an external counter and I
149. 1 Aux Registers ARO 7 Other Registers 14 ALU 6 Comports FIFO IN FIFO OUT PAU Ctl Registers lt p Port Control TimerO Timer 1 TI2 2 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Texas Instruments TMS320C40 36 1 2 TMS320C40 Software Architecture The TMS320C40 has a register based CPU architecture The CPU contains following components a A Floating Point amp Integer multiplier m ALU for floating point integer and logical operators m 32bit barrel shifter m Internal buses CPU1 CPU2 and REG1 REG2 a Auxiliary Register Arithmetic Units ARAU m CPU register file We will only list the CPU registers as these are the most important ones for the applications programmer Asm Symbol Assigned Function Name RO R11 Extended Precision Registers 40 bits These registers are used for 40 bit floating point or for 32 bit integer operations They cannot be used as pointers for indirect addressing ARO AR7 Auxiliary Registers 32 bits These registers can be used for integer operations or for indirect addressing pointers DP Data Page Register Provides the upper 16 bits of a direct memory address IRO IR1 Index Registers Used for some of the indirect addressing modes BK Block Size Register Used for circular and bit reversed addressing SP System Stack Pointer The C40 uses a full asc
150. 1 USTAT2 CFREE 10 r1 r2 r4 r8 r12 i4 112 m4 m12 SYSSET IRPTL IMASK NSWAP i1 i2 i3 i7 MODE1 ASTAT INTSET MODE1 ASTAT rO r1 r2 r4 r8 r12 i4 i12 The CSAVE and CFREE sets are defined by the procedure calling standard ADI 2 12 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the ADSP 2106x SHARC of the C compiler CSAVE is the set of registers that is preserved across a subroutine call if a function uses any of these it must restore the initial value on return CFREE is the set of registers that are freely available to all functions the caller of a subroutine is responsible for preserving them if necessary The definition of these two sets largely determine what the micro kernel is expected to do when swapping tasks When a task is swapped out as a result of calling a kernel service which to the task is just a C function only the CSAVE set need be saved When a task is preempted which means that an interrupt handler has woken up the kernel the CFREE set must be saved as well Actually since most of the microkernel is written in C the CFREE set must be saved before the actual service requested by the interrupt handler is called The SYSSET register are used for system and peripheral control only They are never swapped and should be regarded as global resources Only very low level routines such as hardware drivers will ever need to access these registers The INTSET re
151. 1 55 e SUMMARY e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTE KS SetSlice Set timeslicing period Task void KS_SetSlice K_TICKS ticks K_PRIO prio The KS_SetSlice kernel service will timeslice equal priority tasks if they have a priority lower than the one indicated Note that if there is only one task with the same priority that is runnable the service will have no effect as the task will be rescheduled immediately NONE set the timeslice period to 300 ms for all tasks with a priority below 20 mf KS_SetSlice 300 20 KS_ Yield A low numeric value is a high priority Thus the highest priority task has a pri ority of one This service is only available in Virtuoso Classico Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 93 Alphabetical List of Virtuoso microkernel services 11 56 e SUMMARY e CLASS es ey ees e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES KS SetWlper Set workload period Special void KS_SetWlper int period The KS_SetWlper microkernel service is used to specify the workload mea suring interval The KS_Workload service will return the average workload over the last full period and the current one The period must be specified in milliseconds and be between 10 and 1000 milliseconds NONE set th
152. 10 Nanokernel communications Sie tedcet Sceiet acest elec guns se ahd neat abeens et eeu eee tee dete Tl2 11 C_CHAN Counting channel sciccsiccashectaediesientariastenediandiseedioneraderk TI2 12 L_CHAN List CHANNEL 0 ccc cececeeeceeeeeecsceeeeseneseeeeseee seseeeeaeceeeeeae eae Tl2 12 S_CHAN Stack Channel c ccccccceesesseeeeseaceeseeeseeceesenseseeseeseeeeeseseeess Tl2 13 RGGISter CONVENTIONS ssie a ensue aaia spa a aaa a r a aT ates TI2 13 aeaeaie tare Mla Lo e E T TI2 15 Communicating with the microkernel cc cccceeescseceeeseeeseeeeeseeceeeeseeeaeeeeaeeaees TI2 17 Virtuoso drivers on TMS320040 2 20 deli acbeda pe aeetve eae octane dee resterne trrnserne nent TI2 20 Alphabetical List of nanokernel entry points TI2 22 TANT OF OC OSS iine ereere an a Gee tee tne onan atau ened ape aioe ea Contes eau Eoin Dih TI2 23 SLAM PKO CESS ecsctcites ccs t ncpelcen a E e e a theses EA EEA AE Tl2 24 ENDISRO ao sacha rr a a Rae Re Re NE eh ee oes TI2 25 ENID RT a eee E E A de cede are aa cae tee E E EAE TI2 27 K task all iranin ea a a E aaa a a aaa a eal ia TI2 29 Ko DISABIGIS RO enet e adecdeetten nS Setete dutemss a tebe ies ces TI2 30 KS Enable ISP cicciassseetioccesistuanwatets dhutews a a E eels TI2 31 PRH GET rre ear eaae e aaae aaee AEEA aaa EERE SESE dre OSERE NaS TI2 32 PRHICGETW erreina aa a E aaa TI2 33 PRHIGPOP aen a a a ac alte octagon SR TI2 34 PRL POPW eei ee a a a A a TI
153. 12 IRPTEN Global interrupt enable Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 5 Virtuoso on the Analog Devices 21020 DSP 15 16 17 18 19 20 31 ALUSAT TRUNC RND32 Name IRQOE IRQ1E IRQ2E IRQ3E CADIS TIMEN FLAGOO FLAG1O FLAG2O FLAG3O CAFRZ Enable ALU saturation Reserved truncation rounding single extended precision Definition IRQO edge level sensitive IRQ1 edge level sensitive IRQ2 edge level sensitive IRQ3 edge level sensitive Cache disable Timer enable Reserved FLAGO FLAG1 FLAG2 FLAG3 Cache freeze Reserved 18 4 2 Arithmetic status register ASTAT ASTAT is a 32 bit register in which the bits can be set as a result of an ALU operation An overview of the bits in the ASTAT register is given below Bit OON OOo KR ON O Name AZ AV AN AC AS Al MN MV MU MI Definition ALU result zero or underflow ALU overflow ALU result negative ALU fixed point carry ALU X input sign ALU floating point invalid operation multiplier result negative multiplier overflow multiplier floating point underflow multiplier floating point invalid oper ADI 6 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Analog Devices 21020 DSP 10 11 12 13 14 17 18 19 20 21 22 23 24 31 AF SV SZ SS BTF FLGO FLG1 FLG2 FLG3 ALU floating point operation shifter overflow shifter result zero shifter inp
154. 2 138 Virtuoso Reference Manual Copyright 1996 Eonic Systems Runtime libraries 13 2 6 Text plotting int installuserfont char name Adds a user supplied font to the list of five standard fonts known by the driver void setusercharsize int multx int divx int multy int divy This function can be used for fine scaling of a line font It has no effect on bitmapped fonts void textdimensions char text int x int y Requests pixel dimensions of text void outtext char text void outtextxy int x int y char text Outputs a text at current position or at x y 13 2 7 Other graphical calls The next three calls can be used to implement a simple icon system int getimage int left int top int right int bottom Saves part of the screen to DOS memory This function allocates a block of memory on the host PC and saves part of the graphics screen to this area Returns 0 if the allocation failed a block number otherwise The size of a block is limited to 64K minus a few bytes Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 139 Runtime libraries void void void void void putimage int left int top int block int op Puts a previously saved block on the screen at left top using a selected logical operation see GRINT H for details The block remains in DOS memory and can be replotted any number of times freeimage int block
155. 2 35 PRHE UT derr n a a i tae ee eS TI2 36 ere hn e RR Ce E N eC ore Srey Renton Rane Viren Seer OnE E EN TI2 37 Para Sd sacred eat eat tae bate adele alsa rea Raha SY da eth Godan E tach Rep baad TI2 38 PRA WA iat e e a anata a octets a ccceer canines cae aches TI2 39 PS Fed oarenien a ata sedan ate A eee erate R TI2 40 SS ASM aa 2t O ces nes te cea eae eet arcu ee oe deco tags ta mare ee E A ccere TI2 41 OY SDS a a aa e a E a a aE eaaa a TI2 43 SYSENA sce annaa a a cd oy a sede cate cola ee TI2 44 SOY SVEG hoc i i a E E a elects TI2 45 VUE D E E ET E TI2 47 Predefined drivers TI2 48 Th timer device dhVerS arniran neag EAEN aN AE batons TI2 48 Host interface device drivers a xccsicmccaisnt ac deputeneeye svete oes de es svcd pea eemeenpden re TI2 48 Copyright 1996 Eonic Systems Virtuoso User Manual TOC 13 NOT OLIVElS EEA EEA E TTT EE OOI EEEE ie onsale aten Aale BAET EEE E E EE T TI2 49 Fask Level TIMINGS nussii teira seuss ee spite oats sre ieee eevee ila eee eae TI2 50 Glossary GLO 1 IX 1 Index TOC 14 Virtuoso User Manual Copyright 1996 Eonic Systems Introduction Introduction Virtuoso is a family of real time processing programing systems As this family is expanding it became necessary to differentiate between the differ ent product offerings The general philosophy however is the same ease of use and portability with no compromize on the performance Most of the pro
156. 2ihd neki e era aa lear thee aant idag P2 55 ERA A A bie cot See E AE E tian areas tes tea E A E te seeeecte P2 56 KS LNK ates iiare abate a a a a d ee eek P2 58 Ce aAA A E E E E Sc reer ee P2 59 KS bInKOUt s lt sesenc nies teleate Bl oS lessee eens Bs een ae P2 61 KS EMBOLI VV ssi storey sects norte boner nd dint easier pons emia nadie te debe TAE P2 63 KS LinkoutW P eera a Saiuidenishendsanvensilanaserkawraden RE P2 64 KS LOCK cites cee a a a e aaa ea e a SCOENE sate eTA P2 65 KS CROCK Ws si estas steseaterhtahie tid actuate a Sedasd eee ete Seeded P2 66 PLOW Tce es teen lan Devsten gutta anda pose Nast a a te aad ender cerace tees P2 67 KS SE OWTIMGEN 32 5 32s eisai tel eels E E adele bicelles P2 68 KS MoveData ciatte rr evs dest a e a r a aa P2 69 Poe IOP aces ee dai als cence neta a E a a ke tas as P2 71 Do INO GBI ciceth eSetencast sa a E S aa vase A E ENE AETA P2 72 IS PUGS OUICLIONs lt 6 siscaetana chtes agence cetouetes sat ecnceeeacennconuecweetccaaties enormauers P2 73 Koi ROCCIVE cits ives a ra eaten dedi ok hast ae T a i Rte P2 74 KS RECEIVE Data icciens icv Senduecde sbeveeGeidlenigeteveacti get tanec Mead ea P2 76 KS RECEIVEW memi anana Lats a e voters oie a os daendbels ole eh Metals neaseets P2 78 KS Recone WT foi cee cee nse ievesedgs a e E P2 79 TOC 4 Virtuoso User Manual Copyright 1996 Eonic Systems Pood SOLON E AAE E A E T P2 81 KS RESCISEMAM sisi cctecvstecs ves
157. 3 start of PCS y PR_LINK ae STACK SIZE FIGURE 15 Process Control Structure of a process When a process is swapped in the nanokernel simply pops the first entry on the stack and the process starts at that address When the process termi nates it should perform some clean up actions As the pointer to the termi nation code is already pushed onto its stack the process simply needs to pop that last entry from the stack end jump to that address At that point it will jump to the process termination code To restart a terminated process repeat the call start_process When a PRHI process is swapped in i3 points to the start of the PCS A pro cess can create local variables by incrementing its stack pointer by the num ber of words required Note On the 21060 the stacksize is also a parameter This is because of the stackpointer is moving from the top to the bottom of the stack ADI 2 10 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the ADSP 2106x SHARC 21 7 4 Nanokernel communications A channel type is defined by a data structure and a number of nanokernel services that operate on it Each instance of the data structure is called a channel Channels provide both process synchronization and data commu nication The nanokernel does not itself use or create channels However the ser vices that operate on channels should be considered part of the nanokernel as they may modify
158. 32 bits unsigned long 32 bits signed float 32 bits double 64 bits in L memory pointer address 32 bits absolute address 29 5 2 Segmentation model User variables are allocated storage in one of the following places 1 2 3 The run time stack The D3 D4 D5 D6 R1 R2 R3 and R5 registers The global data area idata_y ildata_L udata_Y and uldata_L seg ments referenced using absolute addressing Separate segments M3 10 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Motorola 96K DSP 29 5 3 Register usage The compiler reserves the following machine registers for particular uses Register Use DO Integer and float return values first parameter value D1 Second parameter value D3 1 D6 1 Integer and character register variables D3 m D6 m D3 h D6 h D3 D6 Floating point register variables R1 R3 and R5 Pointer register variables R6 Frame pointer register FP R7 Memory stack pointer MSP 29 5 4 Subroutine linkage Preserved registers Every procedure is responsible for preserving the following registers D3 D4 D5 D6 R1 R2 R3 R5 R6 and R7 This rule also applies to any assembly language routines called from compiled code Register Return Values The compiler expects function return values in registers under the following circumstances a Pointer values are returned in DO a All non sitructure variables are returned in DO Parameter Passing The first
159. 6 Eonic Systems Virtuoso Binding Manual M1 11 Virtuoso on the Motorola 56K DSP 27 5 4 m Caller Sequence The caller portion of the subroutine calling sequence is responsible for 3 pushing arguments onto the activation record in reverse order 4 the actual subroutine call 5 stack pointer adjustment Additional caller sequence when the subroutine called will return a structure 6 allocate space in the callers activation record to store the return structure 7 pass the return value address in accumulator A m Callee Sequence During the initial portion of the subroutine calling sequence the callee is responsible for 8 saving the return address ssh and the old frame pointer RO 9 updating frame and stack pointers 10 saving the following registers as required B1 BO X1 X0 Y1 YO R1 R5 and R7 Return Sequence During the final portion of the subroutine calling sequence the callee is responsible for 11 placing the return value in accumulator A 12 testing the return value This optimises the case where function calls are arguments to conditional operators Additional callee sequence when the subroutine called will return a structure 13 the return value is not passed in accumulator A A copy of the return struc ture is placed into the space allocated in the caller s activation record and pointed to by accumulator A Procedure Prologue and Epilogue A leaf routine is a subroutine that mak
160. 6 Eonic Systems Virtuoso Binding Manual TI2 9 Programming the nanokernel NANOK_CRIT the critical level This is the number of interrupt handlers running with global interrupts enabled that have not yet terminated All process swapping is disabled while this value is not zero Since the C40 does not support hardware interrupt levels some cooperation is required from interrupt handlers in order to keep this value up to date These five variables together with the IDLE process PCS actually represent all the global information maintained by the nanokernel all other static vari ables are effectively constants In other words the nanokernel only knows about processes that are ready to execute It does not maintain a list of all processes or channels Symbolic constants for accessing kernel variables and elements of a PCS are defined in NANOK INC 37 3 Process management The nanokernel variables are initialized as follows NANOK_PRHI 0 NANOK_HEAD 0 NANOK_TAIL amp NANOK_HEAD NANOK_PRLO amp PCS for IDLE process NANOK_CRIT 0 In other words when an application is started the single thread of execution that exists at that time will be adopted by the nanokernel as its low priority IDLE process In the current version of the nanokernel all PRHI processes must be created and started by the PRLO process it is possible to do this from within another PRHI process but no services are provided to support this
161. 7 Virtuoso on the Motorola 56K DSP 27 3 2 3 27 3 3 PORT C Port C is a triple function I O port with nine pins Three of these nine pins can be configured as general purpose 1 O or as the serial communications inter face SCI The other six pins can be configured as general purpose I O or as the synchronous serial interface Port C can be viewed as 3 memory mapped registers that control 9 I O pins After a reset port C is configured as general purpose I O with all 9 pins as input by clearing all 3 registers The 3 registers are Location Bits Use Port C Control Register PCC X FFE1 0 2 0 Parallel I O 1 SCI 3 8 0 Parallel I O 1 SSI Port C Data Direction Register X FFE3 0 9 0 Input PCDDR 1 Output Port C Data Register X FFE5 0 8 Data Exceptions Exceptions may originate from any of the 32 vector addresses listed in the fol lowing table The corresponding interrupt starting address for each interrupt source is shown also Interrupt Starting IPL Interrupt Source Address 0000 3 Hardware RESET 0002 3 Stack Error 0004 3 Trace 0006 3 SWI 0008 0 2 IRQA 000A 0 2 IRQB 000C 0 2 SSI Receive Data M1 8 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Motorola 56K DSP 000E 0010 0012 0014 0016 0018 001A 001C 001E 0020 0022 0024 0026 003C 003E 0 2 0 2 0 2 0 2 0 2 0 2 0 2 0 2 0 2 0 2 0 2 0 2 0 2 3 SSI Receive Data with E
162. A EE E E E Lae cede ia ies ac as E hs oat P2 108 WS PEST 1 Preteen anaa a stint teed ated is Arenal bead cetaceans P2 110 Kees TestWI eenaa a reeset labisyrace Mes Aa rhiye a aaah P2 111 KS UNOCK ee caudate Seseadartcaer esd elected Sede eees eset eee P2 112 KS HUSCii aici Sscteci chet eta ohcates easel er ieee es ASL Salts Sh Gal eae a phate oo tts P2 113 KS WA as oc tee Sects Gan ten cid aa Mawes dani are tae Aes eara aan oes P2 114 ESEE A i cof EE A at Aes te EA aad eee areata a eed eee P2 115 KS VV INIT cod ise comet aha eee antes Acute e dera aaa cette P2 116 REETA A E E berths cccuccedatcnsteslenee A Oona nit ae tack P2 118 KS WOrklOa d heira eean a a reese a a staal eves P2 119 ESRA LEO RE EEE E AA E E AE E P2 120 Hostserver and netloader P2 121 Host sServer functionality seser er eaer EEn E E AA ER E P2 121 Resetting and booting the target ce cecceeceeeseeeeeceeeeeeeeeeeeeeeeeeeeeeeneneee P2 121 Network Tenin aa eesti vives iestewed Gees dnd ees P2 122 Host interface definition ccccccccccccceseceeeeeesceeeeeseeseeeeseneseeeseseseeesesesea ees P2 122 List of bard Sinai asee a a e a dy NR N A P2 123 Aea E E E E E E E A E A A P2 123 Root node de inition e hina ii see i lee ee P2 124 List of comport links available for booting eeeeceeeeeeeteeeeeeeteeteeeteaeeee eee P2 124 Copyright 1996 Eonic Systems Virtuoso User Manual TOC 5 Host Server interface cecccceececcecccce
163. A easeretee Sees aves ae ce eresete ADI 12 Developing ISR routines on the 21020 oo ceeeceeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeaaes ADI 15 Installing an ISR routine s2iccicchcenieetcieebeenst adeneseeaia aed ADI 15 Writing am ISR routine ives sors Seo canreencens eal AT R ADI 15 Alphabetical list of ISR related services s nonssenenneesseeeeesrneereerrssrresr erreen ADI 18 The nanokernel on the 21020 ca ccccstasenes ced sonesdetscuberspeeecaispenevtatertapeunes eee deaaes ADI 18 FEPOCUICHIOMN soscaire eea TRES t Saian PEAST E EARR EE Ea a TAREKAT EERE ERES Gi ADI 18 Internal data structures ck is each cod ee Senseo eedrn een nee baad saat ethd Camel Gotu etanes ADI 19 Process managment 2c fecter cet haces es ie mececuel tea cece teguateateute ean dante ceeeatiad ADI 20 Nanokernel communications csstsecavieloe sees bedawhe Seventeen eee acon ADI 22 C_CHAN counting channel ci fccecceccecceclecacets set cdaseaces chatbasedeseaseactaeonecennses ADI 22 L GHAN List Channel marnier eaa ee aa a Oi ADI 23 S_CHAN Stack channel ccccccccecccececeecceseeeeeceseseeseeeeseeseeseeeessee eneeees ADI 23 REGISTER CONVENTIONS sspcccceteiee itech ageisdanthadeecndiliwesedinetenedeaeaesees ADI 23 Interrupt handling srren cycles sues insanrn ack Joos iia ia dee uuts TAA Eine tated ADI 25 The ISR l vel ei aeisi a a eaaa e aa aa aa aai ADI 26 Communicating with the microkernel sssssssesssessssserssse
164. AllocTimer P2 34 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services 11 10 e SUMMARY e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES KS Dequeue Get an entry from a FIFO queue Queue int KS_Dequeue K_QUEUE queue void data int size The KS_Dequeue microkernel service is used to read a data element froma FIFO queue If the queue is not empty the first oldest entry is removed from the queue and copied to the address provided by the caller If the queue is empty KS_Dequeue returns with an error code RC_OK if operation succeeds RC_FAIL otherwise char data K_QUEUE DATAQ if KS_Dequeue DATAQ data 1 RC_OK if data startdemo KS_DequeueW KS_DequeueWT KS _Enqueue KS_EnqueueW KS_EnqueueWT The size parameter is the number of 8 bit bytes to be read It should be equal to the width of the queue which implies dequeueing only one entry at a time or unpredictable side effects may occur Care needs to be taken when specifying the size parameter on systems where characters are stored one per word or where sizeof does not return the number of 8 bit bytes in a type Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 35 Alphabetical List of Virtuoso microkernel services 11 11 SUMMARY e CLASS es ey eo
165. C30 Chip Architecture Cache RAM BlockO 64 words 1K Bytes RAM Block1 1K Bytes ROM Block Reserved Local Memory 2 Program and Data Buses Port 3 Program and Data Address Buses 8 MByte 1 DMA Address Bus 1 DMA Data Bus DMA Controller 2 32bit CPU busses 1 Perjpheral Data Bus Global Memory Port 8 MBByte 1 Peripheral Address Bus a p gt lt _ p gt 2 40bit register busses A y 2 Serial ports Reg IN Multiplier 32bit Barrel Shifter Reg OUT ALU Ctl Registers Address amp Disp Registers 40bit registers RO R11 Other Registers 14 Aux Registers ARO 7 ALU Port Control TimerO Timer 1 TH 2 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Texas Instruments TMS320C30 amp C31 35 3 TMS320C30 Software Architecture The TMS320C30 has a register based CPU architecture The CPU contains following components A Floating Point amp Integer multiplier ALU for floating point integer and logical operators 32bit barrel shifter Internal buses CPU1 CPU2 and REG1 REG2 Auxiliary Register Arithmetic Units ARAU CPU register file We will only list the CPU registers as these are the most important ones for the applications programmer Asm Symbol RO R7 ARO AR7 DP IRO IR1 BK
166. DSP Using Virtuoso gives a uniform interface to the programmer while he can modify the target hardware without affecting much the source of his program Copyright 1996 Eonic Systems Virtuoso User Manual P1 41 Simple Examples 5 Simple Examples This section gives a simple example of programming with the Virtuoso micro kernel It illustrates the steps needed to define build and run an application with a single task the famous hello world program Then a more complex example with two tasks communicating via a queue is explained 5 1 Hello world This example illustrates a simple program that uses the stdio library to print a string on the screen Rather than start from scratch it is easier to copy various files from one of the example directories and modify them The files you need are normally as follows sysdef The system definition file makefile Build definition for the make utility The use of make is recommended even in the simplest applications because of the dependencies that arrise from the system definition file mainl c Standard main entry point code which is pro vided in source form for flexibility although for normal applications it does not need to be changed The sysdef file is then edited to the following form NODE NODE1 C40 DRIVER NODE1 HostLinkDma 2 2 PRIO_DMA DRIVER NODE1 TimerO_Driver tickunit Le tasknam
167. EEALSO e SPECIAL NOTES KS Groupld Returns the taskgroup set of the task Task management K_TGROUP KS_GroupId void This microkernel service reads the taskgroup identifier of the calling task Each group is indicated by a bit set in the word The taskgroup identifier K_TGROUP SLAVES if KS_GroupId amp SLAVES do some work since I am a SLAVE i work KS_JoinG KS_LeaveG This service is currently implemented as a macro Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 49 Alphabetical List of Virtuoso microkernel services 11 21 e SUMMARY e CLASS ene ee e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES KS _HighTimer Read the processor s high precision timer Processor specific int KS_HighTimer void This service reads the processor s high precision timer The current high precision clock value tnt TimeNow TimeNow KS_HighTimer KS _Elapse KS _LowTimer The precision and return type are processor dependent On some proces sors reading the high precision timer without using this service may cause unpredictable side effects This service does not actually enter the microkernel and therefore cannot cause a task switch P2 50 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services 11 22 e SUMMARY e SYNOPSIS
168. EM3 EM4 EBUGGO Onn Nn 15 2 8 Resources Oo OW W PF OO CO The resource states are provided in 5 columns Name Count Confl Owner Waiters 2 the symbolic name the number of KS_Lock W requests that were made the number of times the resource was locked when a KS_Lock W request was made the current owner task the tasks in the resource waiting list RESOURCE STATES Name Count Confl Owner Waiters 0 HOSTRES 1 CONRES 2 GRAPHRES 26370 83 TLDEBUG 0 0 574 449 TLDEBUG BALL1 BALL3 15 2 9 Memory Partitions The memory partition information is given six columns Name NCurr Nmax Size Count Waiters the map s symbolic name the number of blocks in use the maximum number of blocks ever used the size of the map as defined at system generation the numbers of time a block of the map was allocated or deallo cated the list of waiting tasks Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 159 Debugging environment under Virtuoso gt a MAP STATES Name Ncurr Nmax Size Count Waiters O MAP1 2 3 4 7 1 MAP2 40 40 40 67 Task3 15 2 10 Tracing monitor MONITSIZE MONITMASK e Note The tracing monitor is a part of the Virtuoso Task Level Debugger During normal kernel activities relevant information about the system is saved in a circular buffer so that the recent history of the sy
169. E_RPL DEQUE_TMO QUE_OP SEND_REQ SEND_RPL SEND_TMO SEND_ACK RECV_REQ RECV_RPL RECV_TMO RECV_ACK ELAPSE SLEEP WAKEUP TASKOP GROUPOP SETPRIO YIELD ALLOC DEALLOC TALLOC TDEALLOC TSTART TSTOP DRIV_REQ DRIV_ACK ALLOC_TMO REMREPLY DEBUG_REQ DEBUG_ACK TXDATA_REQ TXDATA_ACK KS _ Unlock KS_Enqueue internal message for KS_Enqueue W T KS_InqQueue or KS_PurgeQueue KS_Send W T internal message for KS_Send W T id id KS_Receive W T internal message for KS_Receive W T id id KS_Elapse KS_Sleep internal message for KS_ Sleep all operations on a single task all operations on a task group KS_SetPrio KS_Yield KS_Alloc W T KS_DeAlloc W T KS _AllocTimer KS_DeallocTimer KS_StartTimer KS_StartTimer driver call starts driver call returns internal message for KS_Alloc W T internal message many services internal message used by debugger task id KS _MoveData internal message for data transfer protocol P2 162 Virtuoso Reference Manual Copyright 1996 Eonic Systems Debugging environment under Virtuoso RXDATA_REQ KS_MoveData RXDATA_ACK internal message for data transfer protocol RAWDATA_REQ id RAWDATA_ACK id DATAWAIT id EVENTWAIT KS_EventW An example is given below Si VIRTUOSO TL Debugger 3 09 NODE 1 NODE TL MONITOR E1
170. G M MYTYPE MyData MyPtr int SameNode M tx_task ANYTASK M rx_data NULL M size sizeof MYTYPE KS_ReceiveW MAILBOX1 amp M SameNode KS_NodeId M tx_task KS_NodeId M rx_task if SameNode yPtr M tx_data else rx_data MyData KS_ReceiveData amp M yPtr M rx_data use message access via MyPtr if SameNode M size 0 KS_ReceiveData amp M If both tasks are known to be on the same node this could be simplified fur ther as shown below Note that a KS_ReceiveData call with size 0 is still necessary This is the recommended way to pass messages by reference as it is trans parent to the sender and leaves the info field available for other purposes Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 173 Practical hints for correct use 16 2 16 3 void Receiver K_ MSG M YTYPE MyPtr tx_task ANYTASK cx_data NULL size 0 KS _ReceiveW MAILBOX1 amp M yPtr M tx_data use message access via MyPtr x KS_ReceiveData amp M will reschedule sender acts as an ack On the abuse of semaphores In order to synchronize tasks one might be tempted to use semaphores If however also data is to be transferred following the synchronization one should be aware that the use of a semaphore is superfluous as the data transfer itself will synchronize th
171. I 2 38 Virtuoso Binding Manual Copyright 1996 Eonic Systems Predefined drivers m speed SSPEED for single speed DSPEED for double speed For updates on the status of the bidirectional link driver check the readme file included with your release 23 1 4 Raw Link drivers void RawLinkDMA int link_no int buffer_no int speed This is the RAW DMA link driver for the link ports The arguments m link_no buffer_no link buffer you wish to use m speed SSPEED for single speed DSPEED for double speed This driver does not implement any protocol it allows the programmer to transfer receive and transmit specified amounts of data over the link port Also it is not allowed to use a RawLinkDMA on a link that is used as a NETLINK The services which use this driver are KS_Linkin W int buffer int length void addr m KS_Linkout W int buffer int length void addr The specified lengths are in WORDS not bytes 23 1 5 Common remark for all link drivers It is currently not possible to use DSPEED drivers on rev 1 x silicon This will work on rev 0 6 and probably also on later rev 2 0 and on revisions It is possible to assign any link port to any link buffer The driver will check if the requested buffer is already assigned to any other link If so it will simply return and the driver is not loaded This could prevent your application from running correctly so please check the buffer assignments carefully
172. ITIONS The GIE bit in ST is set EXAMPLE trap SYSDIS code to run with interrupts disabled trap SYSENA e SEE ALSO SYSDIS SYSVEC e SPECIAL NOTES This trap can be used inside a C function by using the inline assembly state ment TI2 44 Virtuoso Binding Manual Copyright 1996 Eonic Systems Alphabetical List of nanokernel entry points 38 20 SYSVEC BRIEF Install or remove an interrupt handler CLASS 20 S424 Interrupt service management e SYNOPSYS TRAPcond SYSVEC SYSVEC is defined in TRAPS INC e DESCRIPTION This entry point provides a convenient and safe way to install remove or replace an interrupt handler It takes two parameters an interrupt number and a pointer to an ISR The pointer is entered into the interrupt vector table and if it is not zero the corresponding interrupt enable bit is set in the IIE or IIF register If the pointer is NULL the interrupt is disabled e ENTRY CONDITIONS ARO interrupt number AR1 pointer to ISR or 0 e EXIT CONDITIONS ARO AR1 AR2 and ST corrupted IIE or IIF register modified as described all other registers are preserved EXAMPLE include traps inc ref _ iiiof2_isr create a variable pointing to the isr bss PLOL2 Ts rupeEer 1 Sects cinit word 1 liof2_isr_ptr iiof2_isr text install the ISR ldi 34 ar0 ldi _ iiof2_isr_ptr arl trap
173. It is now required that a section called packets is allocated in internal mem ory to hold all the packets used by the kernel This is done in the architecture file used to link the application This section holds command and datapack ets used to communicate between the kernel and nanokernel processes The size of a command packet is fixed at 16 words and the size of a data packet is defined in mainx c in bytes If there is not enough room in this section the kernel will not operate correctly Also see the provided exam ples Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 2 39 Task Level Timings 24 Task Level Timings Following is a list of task level timings of some of the kernel services pro vided by Virtuoso These timings are the result of a timing measurement on a rev 1 2 ADSP 21062 board with a clock speed of 40MHz The kernel used for these timings is the VIRTUOSO Microkernel All timings are in microseconds The C compiler used is the G21k C Com piler v 3 2d from Analog Devices minimum VIRTUOSO call time 5 SEND RECEIVE WITH WAIT MAILBOX SERVICES header only 39 8 bytes 40 16 bytes 40 32 bytes 40 64 bytes 41 128 bytes 41 256 bytes 43 512 bytes 46 1024 bytes 53 2048 bytes 65 4096 bytes 91 QUEUE OPERATIONS enqueue 1 byte 8 dequeue 1 byte 8 enqueue 4 bytes 8 dequeue 4 bytes 8 enqueue 1 byte to a waiting higher priority
174. K_MSG msgstruc K_TICKS ticks m receive message from mailbox if any int KS_Receive K_MBOX mailbox K_MSG msgstruc m receive message from mailbox and wait till done int KS_ReceiveW K_MBOX mailbox K_MSG msgstruc m receive message and wait with timeout int KS_ReceiveWT K_MBOX mailbox K_MSG msgstruc K TICKS ticks m retrieve message data void KS_ReceiveData K_MSG msgstruc m copy data for size from a source address on a source node to a destination address on a destination node void KS_MoveData int node int size void source void destination int direction 8 6 Queue microkernel services put an entry into a queue int KS_Enqueue K_QUEUE queue void source int size Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 15 Virtuoso microkernel services put an entry into a queue and wait till done int KS_EnqueueW K_QUEUE queue void source int size put an entry into a queue and wait with timeout int KS_EnqueueWT K_QUEUE queue void source int size K_TICKS ticks a get an entry from a queue int KS_Dequeue K_QUEUE queue void destination int size a get an entry from a queue and wait till done int KS_DequeueW K_QUEUE queue void destination int size m get an entry from a queue and wait with timeout int KS_DequeueWT K_QUEUE queue void destination
175. LU Address Generation Unit X Data Memory Y Data Memory Program Controller Program Memory I O Memory Expansion Port A General Purpose O Ports B and C Copyright 1996 Eonic Systems Virtuoso Binding Manual M1 1 Virtuoso on the Motorola 56K DSP Host Interface Serial Communication Interface Synchronous Serial Interface The major components of the Data ALU are as follows m Four 24 bit input registers a A parallel single cycle nonpipelined multiply accumulator logic unit MAC a Two 48 bit accumulator registers a Two 8 bit accumulator extension registers Two data bus shifters limiter circuits The major components of the Address Generation Unit are Address Register Files Offset Register Files Modifier Register Files Address ALU Address Output Multiplexer DSP56000 Block Diagram YAB XAB EXTERNAL ADDRESS BUS m GENERATION Ooo SWITCH ADDRESS UNIT PORT B ae ee b s lt ne 4 328 228 contRoweR gt p lt gt ON CHIP G FAN Zoo a PERIPHERALS OTN p HOSTSSISOI a 9 256x24 256x24 p gt PARALLEL 1 0 rat PORT C AND OR fi YDB SSI SCI INTERNAL DATA R EE BUS ocd ie poe Vv EXTERNAL ogy AND BIT es A A DATABUS Dam MANIPULATION SWITCH UNIT E es _ ty i_ _ _ 16 BITS PROGRAM PROGRAM PROGRAM DATA ALU ie ADDRESS GENERATOR DECODE INTERRUPT CONTROLLER CONTROLLER
176. MT KS Signal KS_SignalM In Virtuoso Classico this service is implemented as a macro P2 118 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services 11 79 KS Workload e SUMMARY Read the current workload e CLASS Special e SYNOPSIS int KS_Workload void e DESCRIPTION The workload microkernel service returns the current workload as a number ranging from 0 to 1000 Each unit equals 1 of the time the CPU was not idling during the last workload measuring interval e RETURN VALUE The measured workload EXAMPLE int wl wl KS_Workload e SEE ALSO KS_SetWlper Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 119 Alphabetical List of Virtuoso microkernel services 11 80 KS Yield e SUMMARY Yield the CPU to another task CLASS Task e SYNOPSIS void KS_Yield void e DESCRIPTION The KS_Yield microkernel service will voluntary yield the processor to the next equal priority task that is runable Using KS_Yield it is possible to achieve the effect of round robin scheduling If no task with the same priority is runable and if no task switch occurs the calling task resumes execution e RETURN VALUE NONE EXAMPLE KS_Yield SEEALSO KS_SetSlice P2 120 Virtuoso Reference Manual Copyright 1996 Eonic Systems Hostserver and netloader 12 Hostserver
177. O TXDATA transmit word sti E pop Al not done yet just end ISR Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Texas Instruments TMS320C30 amp C31 pop ARO continue whatever process popf RO was interrupted pop RO pop ST reti txl_1l bd_kernel_sign_entry send signal TX1INT tokernel ldi TX1INT RO RO ST and return address nop are still pushed on the stack nop the kernel will clean this up Copyright 1996 Eonic Systems Virtuoso Binding Manual TI1 13 Virtuoso on the Texas Instruments TMS320C30 amp C31 TI1 14 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Texas Instruments TMS320C40 36 Virtuoso on the Texas Instruments TMS320C40 36 1 Brief description of the processor architecture This section contains a brief description of the TMS320C40 processor archi tecture It is not intended to be a replacement of the Processor s User Man ual but as a quick look up for the application programmer Detailed information can be found in the TMS320C40 Users Guide from Texas Instruments The TMS320C40 has a Harvard like architecture separated program and data addressing capability with multiple internal buses The interface to the outside world is done via two programmable memory ports Two 4K bytes internal RAM blocks are available as well as a small cache of 512 bytes The C40 has 6 FIFO buffered co
178. ONIDRV 16 35 64 HIQTASK 16 45 64 HIMTASK 16 45 64 SEMATAS 64 16 64 CONDEMO 60 227 256 15 2 15 Zero Queue Map Resource Statistics This command will cause all of the usage statistics for queues memory par titions and resources to be reset No other user input is required Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 165 Debugging environment under Virtuoso 15 2 16 Other processor When invoked you are prompted for a valid processor number and the debugger interface is opened on the requested processor From then on all debugging commands will be executed on the requested processor Example gt 02 15 2 17 Task Manager Note not always implemented Task Manager Mode allows the user to do some types of task management operations via the debug console Selection of this command causes a spe cial prompt to indicate that the debugger is in Task Manager Mode The prompt appears as TLDEBUG 1 gt S STLDEBUG The Task Manager Mode menu may be displayed by responding to the prompt with a H or h followed by an Enter key The Task Manager Mode menu is displayed as shown below S Suspend Resume Abort Start Exit STLDEBUG x HP w Except for the Exit X command all of the commands in the Task Manager Mode require that a task number be entered The task identifier prompt appears as Task gt The user s response to
179. Other mem ber functions called upon a KResource object will result in kernel service calls with the resource ID of the resource object as the first parameter The mapping between member functions and kernel services is the following resource Lock calls KS_Lock RESID resource LockW calls KS_LockW RESID resource LockWT calls KS_LockWT RESID resource UnLock calls KS_UnLock RESID 17 12 KTimer Objects representing kernel timers are of the class type KTimer The class definition is as follows Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 187 Microkernel C interface 17 13 class KTimer private K_TIMER m_pTimer construction destruction public KTimer KTimer access functions public operations public void Start K_TICKS delay K_TICKS period KSemaphore sema void Restart K_TICKS delay K_TICKS period void Stop It is important to note that the calls to KS_AllocTimer en KS_DeallocTimer are wrapped in the constructor respectively destructor of the KTimer object This implies that if a KTimer object goes out of scope the timer that was wrapped by it cannot be used anymore because it will be explicitly deallo cated If one wants to use one specific timer from different places in a pro gram one will either have to allocate a global timer object statically or one must use the operator new to allocate a KTimer object on
180. Other member functions called upon a KTask object will result in kernel service calls with the task ID of the task object as the first argument The mapping between member functions and kernel services is the following task SetEntryFunction calls KS_SetEntry TASKID Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 179 Microkernel C interface 17 4 17 5 task SetPrio calls KS_SetPrio TASKID task Start calls KS_Start TASKID task Abort calls KS_Abort TASKID task Suspend calls KS_Suspend TASKID task Resume calls KS_Resume TASKID KActiveTask The KActiveTask class is introduced to cover the kernel services that operate on the task that calls the service There is thus only one instance of this class and this object is always named ActiveTask in the files generated by sysgen The class definition looks as follows class KActiveTask private construction destruction public access functions public KTask GetTask K_PRIO GetPriority const UNS32 GetGroupMask operations public void JoinGroup KTaskGroup group void LeaveGroup KTaskGroup group The GetTask member is used to retrieve a KTask object representing the current task This temporary object can then be used to call kernel services mapped to the KTask class GetPriority returns the priority of the current running task GetGroupMask returns an u
181. P arl microkernel input channel ldi _CP1P ar2 pointer to command packet nop 37 8 Virtuoso drivers on TMS320C40 Drivers are the interface between the processor and peripheral hardware and the application program They normally serve two purposes data com munication and synchronization As polling is not a recommended practice in a real time system most drivers will use interrupts in one way or another The Virtuoso system does not provide a standard interface to drivers this allows the application writer to optimize this important part of their implemen tation Some basic services that will be required for almost all drivers are provided Most low level details have already been described in the previous sections on interrupt handling and communication with the microkernel At a higher level a typical driver can usually be divided into three functional parts TI2 20 Virtuoso Binding Manual Copyright 1996 Eonic Systems Programming the nanokernel 1 The first component is a function to install the driver This should initialize the hardware and any data structures used and install interrupt handlers for the driver A call to this function is usually placed inside a DRIVER statement in the system definition file The SYSGEN utility copies this call into a func tion named init_drivers it generates in the node c files The init_drivers subroutine is called by kernel_init just before it returns 2 Most dr
182. P1 37 Single processor operation nih decade elon Septet ss Getactwesgdaiedaeesunee tedden sav eha see nennen P1 38 Virtual Single Processor operation 00 0 2 ccceeeceecceeeceeneeees eeseee seas aeeeeneeeaeeeenaeeeeeeaes P1 39 Heterogeneous processor SYSIOMS cccceceeesceenseeeceeeeeeeeeeneeeeeeeeeeen eeseeeeeeseeeees P1 40 Simple Examples P1 42 PION OM WOPG ositee dieicciacth na ensaiicnd E euek exh haa anes euanas nasa S ET P1 42 WSGOT A QUCUG eutsiak ean tes aare ar SE dete EaR a ae ASE aAa heieeentaeteeadeeedere P1 44 Applications P1 46 Scalable embedded systems cccceeccsceeeeseeceeeeeeee neceeeseecaeeeeeeeeesseaaeeeeeteaaeeeeeenaees P1 46 Complex control Systems oriai So cael eae apee a EE a EE EEE aS P1 47 TOC 2 Virtuoso User Manual Copyright 1996 Eonic Systems PART 2 Reference Manual Simulation in the control OOP eee ceeeeeeceeeeeeeneceeeeeeeeseeeeeseeeceeeeseeeceseeeaeeeeeenaeeeeeee P1 47 Fault tolerant SySteMS ccesccecccestaaysiees noinen ene deeded detec NEk ai ietu aSk P1 47 Communication systems esaise sssetel ca te eee feneeetncs ated ear eetbeed eee carers ernn Seams eioa emmena P1 48 Virtuoso microkernel types amp data structures P2 3 Microkernel types csc cee cath seces coreusedanapaes suas cute sh ponlnzentaan sb tvates ehdees un teutel aa teenmrseuiack P2 3 Tasks ierte epuer a e a a a ea eaa a a a a adai P2 3 Task Identifier amp Priority sisrate a a eaaa e
183. Queues are usually used to handle data such as character streams input output or other data buffering A queue is defined by two elements during the system generation process These are 1 the queue size giving the number of entries 2 the queue entry size giving the size of each entry In the current implementation the entry size is limited to 24 bytes when using the multiprocessor version of Virtuoso There is no limitation when the queue is local Resources In any system which uses the concepts of multitasking there is the inevitable problem of two or more tasks competing for a single physical resource A resource might be an external device a block of memory or a data structure These resources as well as others like them usually require that no other task gains access to them during a critical period when a task is operating on that resource To do so might involve the corruption of a data structure or garbling of the output The case is more serious for write access to a resource than for read access but the implications of either case cannot be determined The solution is to protect the physical resource while it is being used by one task so that other tasks cannot gain either read or write access While the solution is obvious the problem is how to grant protection in any possible configuration of Virtuoso Thus the construct called a logical resource or just simply resource In Virtuoso a resource can be anything memo
184. RIO_DMA NODE3 NetLinkDma 0 PRIO_DMA DRIVER NODE1 HostLinkDma 2 2 PRIO_DMA DRIVER NODE1 TimerO_Driver tickunit DRIVER NODE2 TimerO_ Driver tickunit taskname node prio entry stack groups pe E z S TASK STDIODRV NODE1 3 stdiodrv 256 EXE TASK SENDER NODE1 10 sender 400 EXE TASK RECEIVER NODE2 10 receiver 400 EXE queue node depth width i 5 ey QUEUE STDIQ NODE1 64 4 QUEUE STDOQ NODE1 64 4 QUEUE DEMOQ NODE1 10 4 resource node x Af RESOURCE HOSTRES NODE1 RESOURCE STDIORES NODE1 Here the second node is defined at the begining of the file and the netlink driver is declared to set up the connection between the two processors The two tasks SENDER and RECEIVER are declared in the same way as the hello task of the previous example and the queue through which they are to com municate DEMOQ is also declared P1 44 Virtuoso User Manual Copyright 1996 Eonic Systems Simple Examples The sender task is implemented as follows include lt iface h gt include lt _stdio h gt include allnodes h void sender int data 42 printf Sending d to queue n data KS_EnqueueW DEMOQ amp data 4 And the receiver is implemented as follows include lt iface h gt include
185. RQ This C callable kernel service can be used by a an application task to wait for a signal given by an ISR It forms a pair with kernel service Fkernel_sign_entry Fkernel_sign_entry M1 22 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Motorola 56K DSP 27 8 Developing ISR routines When developing Interrupt Service Routines the ISR conventions described in paragraph 27 6 1 have to be followed The best place to install and enable an ISR is in procedure main where predefined drivers like the driver for the timer interrupt are installed and enabled It is possible that additional initialization of registers and or peripheral I O has to be done The best way to do this is writing a C callable procedure that does the necessary additional initializations and call this procedure after the call to KS_EnableISR An example of this method is the installa tion of the timer ISR in procedure main include iface h extern void timerO_irgh void extern void timerO_init void int main void KS_EnableISR 4 timerO_irgh IPLEVEL2 IPMNEDGE timerO_init note When the timer is implemented by means of the internal timer DSP56002 the first argument of the KS_EnableISR and KS_DisableISR has to be 30 See section The timer device driver 27 9 The nanokernel on the 560
186. RQB then the first argument has to be 4 If the timer ISR is installed and enabled the application programmer can read out the timer in high and in low resolution a In low resolution the number of kernel ticks default milli seconds are returned As this value is a 48 bit wraparound value it is more inter esting to calculate the difference between two values which were read out consecutively However to facilitate this kernel service KS_Elapse is written for this purpose The services KS_Sleep and KS_LowTimer also use this low resolution service m The KS_HighTimer service provides a high resolution timer by returning the number of timer counts The units of this value depends of the clock speed of the counter This service is not provided when the internal timer is used since this counter can not be read In this case the high resolution timer value will be equal to the low resolution value See the Alphabetical List of Virtuoso kernel services earlier in this manual for a full description of these kernel services The timer device driver reserves event signal number 48 for its use The host interface device driver The host interface driver is installed by calling procedure init_server In the examples that accompany the release of the Virtuoso kernel the M1 24 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Motorola 56K DSP installation of the host interface is done in procedure main
187. S e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES KS_LinkoutWT Write a datablock to a link with timed out wait Processor specific int KS_LinkoutW int link int size void datablock K_TICKS ticks This call writes data to a processor link The call returns when the writing of the datablock has finished or when the timeout has expired Meanwhile the calling task is put into the LINKWAIT state RC_OK if writing is finished before the timeout expires RC_TIME otherwise static char chanmessage This is a test message n int msgsize Int RetCode msgsize strlen chanmessage RetCode KS_LinkoutWT 3 msgsize chanmessage 100 if RetCode RC_OK printf write of message timed out n KS_Linkout KS_LinkoutWT KS_LinkinW KS_LinkinWT iface h This service is only implemented on transputers Reading from a link without using this service will have unpredictable side effects The size parameter is the number of 8 bit bytes to be written Care needs to be taken when specifying the size parameter on systems where characters are stored one per word or where sizeof does not return the number of 8 bit bytes in a type P2 64 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services 11 33 KS Lock e SUMMARY Lock a resource e CLASS Resource e SYNOP
188. SIS int KS_Lock K_RES resource e DESCRIPTION The KS_Lock microkernel service provides a generalized way of protecting a logical resource If the resource is busy at the time of request the call returns with an error code If the resource is available the resource is marked BUSY to prevent others from using it The logical resource can be anything such as a shared database non reentrant code an I O server etc Nested lock requests by the current owner are supported KS Unlock requests by non owners are ignored e RETURN VALUE RC_OK if successful RC_FAIL if otherwise EXAMPLE K_RES GRAPHRES K_SEMA BUZZER if display is in use use buzzer to give warning if KS_Lock GRAPHRES RC_OK KS_Signal BUZZER else display_warning KS_Unlock GRAPHRES e SEE ALSO 2 24 KS _LockW KS_LockWT KS_Unlock KS _UnlockW KS_UnlockwW Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 65 Alphabetical List of Virtuoso microkernel services 11 34 KS LockW e SUMMARY Lock a resource with wait e CLASS Resource e SYNOPSIS int KS_LockW K_RES resource e DESCRIPTION The KS_LockW microkernel service provides a generalized way of protect ing a logical resource If the resource is in use at the time of request the call ing task is inserted into the waiting list in order of priority If the resource is available the resou
189. SP ST DIE IIE IIF RS RE RC PC IVTP TVTP Assigned Function Name Extended Precision Registers Auxiliary Registers Data Page Register Index Register 0 Index Register 1 Block Size Register System Stack Pointer Status Register DMA Coprocessor Interrup Enable Register Internal Interrupt Enable Register IOF Flag Register Repeat Address Register Repeat End Address Register Repeat Counter Program Counter Interrupt Vector Table Pointerr Trap Vector Table Pointer Copyright 1996 Eonic Systems Virtuoso Binding Manual TH 3 Virtuoso on the Texas Instruments TMS320C30 amp C31 35 3 1 35 4 35 5 Addressing Modes The TMS320C40 addressing modes can be partioned into 4 groups In each group two or more addressing types are provided 1 General Addressing modes Register Operand is register Immediate Operand is 16bit immediate value Direct Operand is 24bit address Indirect Addres is in 24bit Auxilairy Register 2 Three Operand Addressing Mode m Register see above r a Indirect see above m Immediate see above 3 Parallel Addressing Modes m Register Operand is extended precision register a Indirect see above 4 Long immediate adressing mode mOperand is 24 bit immediate value 5 Branch Adddressing Modes m Register see above m PC relative A signed 16bit displacement is added to the PC Relevant documentation It is highly recommended to read carefully the following documentation av
190. SR 2 Registers X B R1 and R2 have to be saved at the start of the ISR after the prior increment of R6 with the sequence as indicated see also previous paragraph Prior to jumping to the entry Fkernel_sign_entry register B1 must be loaded with the event number between 0 and 63 inclusive A JMP instruction must be used to jump to the entry Fkernel_sign_entry not a JSR instruction The System Stack of the processor will be managed by the kernel so that when returning from interrupt the correct program address will be loaded in the Pro gram Counter This kernel service is only callable from an ISR written in assembly when used with the single processor version with no nanokernel Copyright 1996 Eonic Systems Virtuoso Binding Manual M1 19 Virtuoso on the Motorola 56K DSP 27 7 2 KS DisablelSR e BRIEF Disables to ISR to be triggered by interrupt SYNOPSYS void KS_DisableISR int IRQ e DESCRIPTION This C callable service disables an ISR by writing an ILLEGAL instruction at the appropriate place in the interrupt vector table Also for the following inter rupts the corresponding bits in the IPR register of the processor will be changed accordingly a IRQA a IRQB a Host Command Other interrupts can also be disabled by this service but only in the sense that the JSR instruction at the corresponding place in the interrupt vector table will be overwritten by an ILLEGAL inst
191. Se E P2 28 KS lt AllOG peie ea e N E a a nies Res P2 29 KS AlO sea e sod aaumarisainaeicea aia aah a e a a e nantedee P2 30 TG ANOEW T diriana a la dda ete E dw ntien ea tara ET P2 31 KEAR ANE EE E stags T E E hae Mecaedhaatie cede P2 32 KS Deallot mnnn a a a E AAE E EAR P2 33 KS De6alloc HINGE Anas san ET EN P2 34 KS Deg g e 26 censeeahel leat cee ecataarea thst bs tee E AEE EAA EAN Aaaa AAA Aeh P2 35 KS D gueueW saisisit aana eaaa ed a a iaeiaiai P2 36 KS Dequeue Wp sireenin e te araa AE E E P2 37 KS Disablel SR rea a aO AT Ea E a EE P2 39 NEAS 8c E em eee eee eee enero en ee ert oe aane eer Serer E eater P2 40 KS EnablelSR eiior a a bent a Gan emer ea P2 41 eMo ET E Sear E adie Neale E a al dates sit ir eet aad E P2 42 Rec ale OKEI EAA ciicoas ee Ankle pieces mths ca E E itt ia Gl ae Site P2 44 PS at ICUS ISN te eg aerate E ccal ace ct me eaeete chat cctedratra cd tad easataearens P2 46 KS IEVENtW tiii a kel E cede Aiden eee este P2 48 KS Grupla ce eee aeta e E aan tal corederee e ENRON AAi EAEE EENES ENE t P2 49 KS lt HIGM TIM M i nir a aaa aa a a aa a AE REE Mavens P2 50 TSUNA otc ce 5 Ma sae Ria ala eae te Ocha dha Bl tle Se lnc ee daca AS P2 51 KS INQQUGUGC dii AE RR A E AERE TARS P2 52 KS INQ OSM taner reer ireen aa a sea E dareena aR a Ese atar tics P2 53 KEO E aed Ae essah Cates ents asa as nda ince Panta E ss tae dane scaian the hemeesa dd xaaaancedatan tite P2 54 KS Ee aveG x
192. Se eh om x MAILBOX MAILB1 ROOT resource node GPA a ay a a oe ae ee ee x RESOURCE HOSTRES ROOT RESOURCE STDIORES ROOT RESOURCE DEMORES ROOT vkob1 cpp FILE MADE BY VIRTUOSO SYSGEN Version 3 00 DO NOT MODIFY EDIT SOURCE FILE sysdef AND REMAKE The actual overhead is compiler dependent The overhead of 1 C object is at least 4 bytes but most of the memory overhead is actually caused by the size of the C initialization routines P2 190 Virtuoso Reference Manual Copyright 1996 Eonic Systems Microkernel C interface vkobjcts cpp FILE MADE BY VIRTUOSO SYSGEN Version 3 00 DO NOT MODIFY EDIT SOURCE FILE sysdef AND REMAKE System wide kernel objects include vkobjcts hpp include vkacttsk hpp include vktask hpp include vktskgrp hpp include vkmbox hpp include vksema hpp include vkres hpp include vktimer hpp include vkqueue hpp include allnodes h KActiveTask ActiveTask TaskGroup ExeTaskgroup EXE_GROUP TaskGroup SysTaskgroup USR_GROUP TaskGroup FpuTaskgroup FPU_GROUP Node ROOT 0x00010000 Task StdiodrvTask STDIODRV Task HiqTask HIQTAS Task HimTask HIMTAS Task HisTask HISTAS Task MasterTask MASTER r r r Queue StdiqQueue ST Queue StdoqQueue ST Queue DemoqxlQueue Queue Demogx4Queue DIQ DOQ DEMOQX1 DEMOQX4 Semaphore Semaphore Semaphore Sema
193. Short Data m Absolute Address Copyright 1996 Eonic Systems Virtuoso Binding Manual M3 7 Virtuoso on the Motorola 96K DSP 29 3 2 29 3 3 29 3 4 m Absolute Short Address m Short Jump Address m O Short Address a Implicit Reference The DSP96002 Address Generation Unit supports linear modulo and bit reversed address arithmetic for all address register indirect modes Address modifiers determine the type of arithmetic used to update addresses Address modifiers allow the creation of data structures in memory for FIFOs queues delay lines circular buffers stacks and bit reversed FFT buffers Each address register Rn has its own modifier register Mn associated with it Following modifier classes are supported by the DSP96002 Linear Modifier Reverse Carry Modifier Modulo Modifier Multiple Wrap Around Modulo Modifier I O memory and special registers Internal I O peripherals occupy the top 128 locations in X memory space External I O peripherals occupy the top 128 locations in Y memory space Register IPR in the X DATA memory space is used to program the Interrupt Priority for the DMA channels the Host interfaces and the external interrupts IRQA IRQB and IRQC IPR is located on address X F FFFFFFF Register PSR is the Port Select Register and is located on address X FFFFFFFC Every memory space X Y and P is divided into 8 equal portions of each 0 5 gigawords in length PSR is used to map each of tho
194. T8 6 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the INMOS T2xx T4xx T8xx tion as well as their timing 3 Most of the code will be cyclic 4 The application is often stand alone As such most of the program will be spent in a periodic loop while aperiodic events such as alarm conditions are relatively rare however when the latter occur the designer needs to be sure that these will be handled immediately and without being interrupted Hence such a control program will consist of a number of tasks each with its own static priority The designer will assign highest priority to the critical ape riodic tasks while the periodic tasks receive an application dependent prior ity eventually started by a master timer process Note that by using a preemptive task scheduler tasks that require no attention will not consume any CPU time resulting in an overall efficient use of processor resources These requirements are illustrated in Figure 2 that shows how a critical task will start immediately and stay running until termination when using a pre emptive scheduler 33 8 Small grain versus coarse grain parallelism In essence there is no difference between a user task communicating with the outside world or with a process having a different priority Both will result in a process being removed from the current process queue hence breaking the linked list continuity as known by the kernel Therefore all tasks ar
195. VALUE EXAMPLE SEEALSO e SPECIAL NOTES KS Dealloc Deallocate a block of memory Memory management void KS_Dealloc K_MAP map void block KS_Dealloc returns a memory block to the free pool of the specified map A task switch will occur if an higher priority task was waiting for a memory block of the same partition NONE typedef void MyBlock MyBlock p K_MAP MAP1K int RetCode RetCode KS_AllocW MAPI1K amp p if RetCode RC_OK printf Cannot allocate memory n code that uses memory block 2 KS_Dealloc MAP1K amp p KS_Alloc KS_AllocW The microkernel does not check the validity of the pointer argument The user should ensure that blocks are deallocated to the same memory partition they were allocated from and only once Using an invalid pointer will have unpredictable side effects Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 33 Alphabetical List of Virtuoso microkernel services 11 9 KS DeallocTimer e SUMMARY Deallocate a timer CLASS Timer e SYNOPSIS void KS_DeallocTimer K_TIMER timer e DESCRIPTION U EAR microkernel service returns a timer object to the timer pool e RETURN VALUE NONE EXAMPLE K_TIMER my_timer my_timer KS_AllocTimer get timer a KS_StartTimer my_timer 10 0 NULL KS_DeallocTimer my_timer return timer SEEALSO KS_
196. W This entry point must not by called from the low priority context but it can be used by interrupt handlers The first word of the packet is used as a link pointer and will be overwritten ADI 42 Virtuoso Binding Manual Copyright 1996 Eonic Systems Alphabetical List of nanokernel entry points 19 12 PRHI_ PSH BRIEF Push a word on a stack channel e CLASS Process communication e SYNOPSIS PRHI_PSH PRHI_PSH is defined in macro h e DESCRIPTION If a process is waiting on the channel the data word is passed on and the waiting process is rescheduled Otherwise the data word is pushed on the stack In either case control returns to the caller e ENTRY CONDITIONS i4 pointer to channel r2 data word to push e EXIT CONDITIONS r0 rl r4 and r8 are corrupted All other registers are preserved EXAMPLE include macro h extern _K_ArgsP microkernel input stack send a command packet to the microkernel assume i0 points to the command packet i4 dm _K_ArgsP r2 dm 0 10 PRHI_PSH SEEALSO PRHI_POP PRHI_POPW e SPECIAL NOTES This entry point must not by called from the low priority context but it can be used by interrupt handlers Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 43 Alphabetical List of nanokernel entry points 19 13 PRHI_SIG e BRIEF Send an event ona signal channel e CLASS Pro
197. With Virtuoso FIFO queue multiple priority queue ISRI limits lower upper lower upper 5 processes 1 8100 20 140 in queue 10 processes 1 18100 20 140 in queue direct context switch 6 Typical ISRI limit values in microseconds 33 4 A solution based on process priority To be correct the transputer has features that enable it to meet hard real time constraints provided one is willing to give up most of the benefits of the CSP model The transputer knows two priority levels each with its own pro cess queue Whereas a low priority process will be descheduled by a higher priority process at the next instruction a high priority process cannot be interrupted A feasible design methodology is then to let a high priority pro cess accept the interrupt interrupt handling and forward the actual han dling to a low priority process for interrupt servicing However to achieve Copyright 1996 Eonic Systems Virtuoso Binding Manual T8 3 Virtuoso on the INMOS T2xx T4xx T8xx 33 5 timely execution the resulting program will consist of a short high priority process with at most one low priority process The unpredictable timing of the multi tasking program is avoided by implementing a single task program Hence the designer is back at sequential programming and processor cycles will be wasted More complex programming techniques are possible such as the artificially shortening of the hardware fixed timeslice usi
198. YNOPSYS ENDISR1 ENDISR1 is defined in macro h e DESCRIPTION This entry point must be called to terminate an ISR running at level 1 global interrupts enabled It decrements the level 1 interrupt counter and preforms a nanokernel process swap IFF a the calling ISR interrupted the PRLO process m a high priority process is ready to execute e ENTRY CONDITIONS The ISR should have saved the interrupted context so that the exit sequence listed below would correctly terminate the ISR e EXIT CONDITIONS This call terminates the ISR and does not return EXAMPLE This ISR accepts the IIOFO external interrupt and sends a signal to two hi priority processes include def21020 h include macro h segment pm seg_pmco global _rx_host_irqh endseg segment dm seg_dmda var HOST_EVENT 8 extern _K_ArgsP endseg segment pm seg_pmco _rx_host_irgh dm i7 m7 MODE1 register of the INTSET that must dm i7 m7 ASTAT be saved dm i7 m7 r0 dm i7 m7 rl dm i7 m7 r2 dm i7 m7 r4 dm i7 m7 r8 dm i7 m7 r12 r4 i4 dm i7 m7 r4 dm i7 m7 i12 Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 33 Alphabetical List of nanokernel entry points i4 dm _K_ArgsP i4 contains the channel r2 dm HOST_EVENT r2 contains data PRHI_PSH signals channel ENDISR1 ends interrupt en
199. _TICKS ticks e DESCRIPTION The KS Receive message microkernel service operates like the KS _ReceiveW microkernel service except that the waiting is limited to time out ticks e RETURN VALUE RC OK if successful RC_TIME if not successful EXAMPLE K_MSG msg K_MBOX MAIL1 K_TASK ANYTASK char data 256 msg size 256 msg tx_task ANYTASK msg rx_data data if KS_ReceiveWT MAIL1 amp msg 100 RC_OK printf Received d bytes from d n msg size msg tx_task else printf Timed out on receive n SEEALSO KS Send KS_SendW KS_SendWT KS_ Receive KS _ReceiveW KS_ReceiveData Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 79 Alphabetical List of Virtuoso microkernel services e SPECIAL NOTES The size member is the number of 8 bit bytes in the message Care needs to be taken when specifying sizes on systems where characters are stored one per word or where sizeof does not return the number of 8 bit bytes in a type P2 80 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services 11 45 KS ResetSema e SUMMARY Reset the semaphore count to zero e CLASS Semaphore e SYNOPSIS void KS_ResetSema K_SEMA sema e DESCRIPTION The ResetSema microkernel service resets the semaphore count to zero and hence erases all previous signalling operations This microkernel ser vice
200. a tion to be distributed over several processors so that eventually all tasks can really execute in parallel 4 7 About objects and services 4 7 1 The Virtuoso microkernel objects and the related services As described above Virtuoso provides a tool to organize the behavior of a real time program that is composed of several tasks The philosophy behind this is one of tasks that coordinate and synchronize through the common use of so called microkernel objects Tasks themselves are also microkernel objects but they play a dominant role Together with the kernel they are the originators of all the actions that use the microkernel objects to achieve the desired result Each type of microkernel object can be looked upon as being part of a Class on which different operations are permitted Each operation must follow the specified semantics Figure 1 shows the relationship inde pendent of where the objects are located in the system between a number of tasks and the way they use objects to synchronize and communicate Ina single processor system all these objects are located on the same node but in a parallel processing system Virtuoso permits these objects to be located on any processor in the system except when they are tied to the use of spe cific external hardware This was possible through the use of unique names for the objects On the next pages we describe these classes in a general way 4 7 2 Class Task 4 7 2 a The task as a unit
201. aeseeeeaaeeeeeeaas P2 141 Kernel objects riinan asnay e AA tua a ES P2 141 Sysdef system definition file format oo eee cceeeeee eee eeeeeeceeeeeeeeeeeeeeeeeeeeteaeeeeeenaes P2 142 Description requirements for the kernel object types ccceeeeeeeeeeeeeeees P2 144 Node descfiption perpera ua piesei abaan iaa AENEA Eetika A kpene P2 145 Driver description srisisosiar i anini eoa teas ia aiki A ESTANTA cave TIAE at Sere P2 145 Link desg iPtionS avre tedrisat e ea a aT a A aa e aR cast P2 146 The routi g tables esirning aieiaieo a AAE aeia P2 148 Task definitions eyit eeue e a e aee Eae EER aae RRETARA AERES P2 149 Semaphore definitions 2 ceccsereieres texsenened vedeesdesauaczne ted eteabettecesavinn orrnstnnnrnreensee nenene P2 150 Res rce definitions 22 22sec ect acca gh inmate Get ote Raia cnn NER eh Rha as P2 150 Queue definitions 2 ccctastinardincanacittaantecacteemenseeastiecatea tel ieinadntacntteatieaes P2 150 Ma OX CGT IONS ssie a a a a eh oad eee P2 151 Memory map definitions sear secuiaseisseaues the aces ses Seeevaac dgainnae vides actdie can denndtexeceetelengcee P2 151 Note on the size parameters ccceceeceeeeceeeceeeeeeee eeseeeeee cee eeeseeeeeeeeseeeeeeseeneneeee P2 151 Other system information and system initialization cceeeeeeeeeeeeeeeeeeeee teens P2 152 Debugging environment under Virtuoso P2 154 Task level debugger concepts nvcne seceutens santeteteestnPtwandesieyeetiasbi
202. ail able from Texas Instruments In this manual we only outline the main TMS320C3x User s Guide Texas Instruments 1991 Edition TMS320 Floating Point DSP Assembly Language Tools Texas Instruments 1991 TMS320 Floating Point DSP Optimizing C Compiler Texas Instruments 1991 Application development hints The easiest way to start is to copy and modify one of the supplied examples Some of the necessary files have fixed names so each application should be put in a separate directory The following files will be needed for each application TI 4 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Texas Instruments TMS320C30 amp C31 SYSDEF the Virtuoso system definition file The SYSGEN utility will read this file and generate NODE1 C and NODE1 H MAIN1 C this contains some more configuration options and the main function A number of configuration options are defined in this file so they can be changed without requiring recompilation of all sources this would be neces sary if SYSDEF is modified CLCKFREQ this should be defined to be the clock frequency of the hard ware timer used to generate the TICKS time For a C30 this is 1 4 of the CPU clock frequency TICKTIME the TICK period in microseconds TICKUNIT the TICK period in CLCKFREQ units TICKFREQ the TICK frequency The number of available timers command packets and multiple wait packets are also defined in this
203. akefile nodbg mak M2 2 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Motorola 68030 systems link list files demo lnf demo_nodbg 1lnf The include files siotags h and tstdio h are only needed in directory TEST_SIO Source file demo c contains the source code for the application node1 c and node1 h are files that are created by the system generation utility At this moment however the system generation utility is not yet ready so that the present version of node1 c and node1 h are customized for the demo applications In node1 c one can find the definitions of all kernel objects used in the application the task control blocks queues memory maps mail boxes semaphores resources and the names of the kernel objects for debugging purposes Since no OS 9 kernel is present on the target processor board the applica tion with the Virtuoso kernel will have to be able to run on its own There fore the link option r is used in the makefiles to build a raw binary file for a non OS 9 target system When building an application care must be taken during linking phase The order in which the relocatables are linked into one application executable is not important except for one module starter2 r This module must ALWAYS be the FIRST MODULE in the link list because this module con tains the startup code of the kernel and calls to initialization routine
204. all Nop 1 5 Message transfer Send Receive with wait Header only 2 34 16 bytes 2 37 128 bytes 2 46 1024 bytes 2 118 Queue operations Engueue 1 byte 1 9 Dequeue 1 byte 1 9 Enqueue 4 bytes 1 Dequeue 4 bytes 1 10 Enqueue Dequeue with wait 2 35 Semaphore operations Signal 1 6 ADI 50 Virtuoso Binding Manual Copyright 1996 Eonic Systems Predefined drivers Signal Wait 2 28 Signal WaitTimeout 2 34 Signal WaitMany 2 37 Signal WaitManyTimeout 2 43 Resources Lock or Unlock 1 7 Note 1 involves no context switch 2 involves two context switches Timing is round trip time 20 2 Application development hints The easiest way to start is to copy and modify one of the supplied examples Some of the necessary files have fixed names so each application should be put in a separate directory The following files will be needed for each application SYSDEF The VIRTUOSO system definition file The SYSGEN utility will read this file and generate NODE1 C and NODE1 H MAIN1 C This contains some more configuration options and the C main function Copy from one of the examples A number of configuration options are defined in this file so they can be changed without requiring recompilation of all sources this would be neces sary if SYSDEF is modified CLCKFREQ this should be defined to be the clock frequency of the
205. all then acts as an ACK for the sender The C syntax struct of the message header is as follows typedef struct INT32 size size of message bytes void tx_data pointer to data at sender side void rx_data pointer to data at receiver side K_TASK tx_task sending task K_TASK rx_task receiving task INT32 info information field free for user K_MSG Note that it is also possible to copy data directly using the KS_MoveData service However this service requires that correct pointers are provided using other techniques before Because this technique permits to perform Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 7 Virtuoso microkernel types amp data structures 7 5 7 6 this synchronization operation only once it provides for much better performance Queues Virtuoso supports first in first out FIFO queues having single or multiple bytes per entry The queues support both a single producer and a single consumer as well as multiple producer consumer services Queues are addressed with an identifier that is unique to each queue Queue identifiers are assigned in the system generation procedure Virtuoso queues are different from messages because queue entries act as buffers for the actual data Another difference is that the queue entries represent the chronological order of processing Also the priorities of the sender or receiver are not considered
206. allel The output of any computation unit may be the input of any computation unit on the next cycle The computation units input data from and output data to a register file that contains sixteen 40 bit registers and sixteen alternate registers The register file is accessible to the ADSP 21020 program and data memory data buses for transferring data between the computation units and external memory or other parts of the 21020 Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 1 Virtuoso on the Analog Devices 21020 DSP Both fixed point and floating point operations are supported Floating point data can be either 32 or 40 bits wide Extended precision floating point for mat 8 bits of exponent and 32 bits of mantissa is selected if the RND32 bit in the MODE1 register is cleared If this bit is set the normal IEEE precision is used 8 bits of exponent and 24 bits of mantissa Fixed point numbers are always represented in 32 bit format and occupy the 32 most significant bits in the 40 bit data field They may be treated as fractional or integer numbers and as unsigned or twos complement Cache 1 Program f Sequencer PMA bus 24 bits je DMA bus 32 bits PMD bus 48 bits DMD bus 40 bits BUS Connect JTAG test amp emulation a REGISTER i multiplier shifter ALU FILE a ji The ALU performs arithmetic operations on
207. alog Devices 21020 DSP data address generators This DAGs allow the processor to address memory indirectly An instruction specifies a DAG register containing an address instead of the address value itself The first DAG is used in combination with the data memory while the second DAG produces 24 bit addresses for program memory Other functions supported by the DAGs are circular buffers using the L registers and B registers DAG1 can support bit reverse operations This operation places the bits of an address in reverse order to form a new address There are two ways in which an I register can be modified using an M regis ter pre modify without update PM M 1 amp DM M l post modify PM l M amp DM I M 18 4 Special purpose registers on the ADSP 21020 The ADSP 21020 is provided with some special purpose registers This paragraph contains a brief overview of these registers 18 4 1 MODE1 register and MODE2 register MODE1 and MODE2 are both 32 bit registers that enable various operating modes of the ADSP 21020 a MODE1 Bit Name Definition 0 Reserved 1 BRO Bit reverse for l0 2 SRCU Alternate register select 3 SRD1H DAG1 alternate register select 7 4 4 SRD1L DAG1 alternate register select 3 0 5 SRD2H DAG2 alternate register select 6 SRD2L DAG2 alternate register select 7 SRRFH Register file alternate select 10 SRRFL Register file alternate select 11 NESTM Interrupt nesting enable
208. an be used by interrupt handlers TI2 38 Virtuoso Binding Manual Copyright 1996 Eonic Systems Alphabetical List of nanokernel entry points 38 15 PBIB sa ye ecient cas e CLASS See es e SYNOPSIS e DESCRIPTION e ENTRY CONDITIONS e EXIT CONDITIONS EXAMPLE SEEALSO e SPECIAL NOTES PRHI_WAIT Consume an event from a signal channel or deschedule Process communication LATcond PRHI_WAIT PRHI_WAIT is defined in TRAPS INC If the event counter is not zero it is decremented an control returns to the caller If the event counter is zero the calling process is swapped out and set to wait on the channel It will be rescheduled by the next call to the PRHI_SIG service on the same channel AR1 pointer to signal channel struct AR3 pointer to PCS of calling process ARO AR1 AR2 R11 and ST are corrupted include traps inc assume AR5 points to a parameter struct wait for event on SYNC_CHAN lat PRHI_WAIT ldi ar5 SYNC_CHAN arl nop nop the event has happened PRHI_SIG This service must not be called from the low priority context or by an isr Copyright 1996 Eonic Systems Virtuoso Binding Manual Tl2 39 Alphabetical List of nanokernel entry points 38 16 PRLO_PSH e BRIEF This call is for internal use only and is not exactly the equivalent of PRHI_PSH for the PRLO process This call assumes that a PRHI process is waiting on th
209. an object e g the processor location or the stack size of a task one changes the file and invokes the system generation utility Sysgen on it to regenerate all the necessary include files The only thing left to do is to write the actual code of the task s function using the microkernel services The debugger is a task level debugger When invoked it suspends all the tasks in the system on all processors and permits the user to jump to any processor in the system to examine the current state of all the defined objects The tracing monitor is integrated with the debugger and permits to inspect a system trace in which the last 256 scheduling events were recorded Finally Virtuoso intends to be more than a simple bare bones real time ker nel Functions are provided that give access to system resources normally found on a host system We strongly believe in this approach as it relieves the target environment from the burden of the development utilities and hence provides for a optimal use of the system resources The graphical server is an extension of the host server program that permits to perform some elementary graphics on the host screen from any task in the network In general a standard I O server console I O and simple file I O with the host file system is always supplied Note that there also exists a complementary product that contains a general purpose as well as specialized library of mathematical and signal processing funct
210. an provide for very good performance However if one of the tasks is now moved to another processor passing the pointer has become a mean ingless operation Hence this program is not scalable Using global variables leads to similar problems For above reason the semantics of Virtuoso reflect the non locality of pointers If wished the user can exploit it for maximum performance but he will be warned because his program code will show it In any case using local variables always lead to safer and more modular pro grams and is good programming practice anyway Similarly embedding task functions in a single large file leads to problems when rebuilding the application The safest practice is to compile each task function separately and add them all to a single task library Upon linking the linker will then only add the relevant task functions to the executable images avoiding the generation of unnecessary large executables Copyright 1996 Eonic Systems Virtuoso User Manual P1 9 Virtuoso an overview 3 Virtuoso an overview 3 1 3 2 3 2 1 Requirements for a programming system Processor technology is changing very rapidly Processors are becoming faster microcontrollers are becoming more complex and richer in features but developers are left with the impossible task to keep up In addition funda mental I O bandwidth limitations force the designers to go parallel to reach the required level of performance The co
211. and RETI The ISR1 level An interrupt handler running at the ISR1 level is known to the kernel and is allowed to modify the global interrupt enable state Calling the SETISR1 ser vice moves an interrupt handler from the ISRO to the ISR1 state The kernel increments NANOK_CRIT and returns with interrupts enabled GIE 1 After having called SETISR1 the ISR is allowed to directly modify the GIE bit as often as required It must always terminate by calling the ENDISR1 ser vice The kernel decrements NANOK_CRIT and then performs the same test as for ENDISRO SETISR1 is implemented so that it can be called very early in an ISR Only the ST and R11 registers are modified and must have been saved Sophisticated interrupt priority schemes can be set up by manipulating indi vidual interrupt enable bits before calling SETISR1 If this is done the origi TI2 16 Virtuoso Binding Manual Copyright 1996 Eonic Systems Programming the nanokernel nal state of the IIE and IIF registers must be restored before terminating the ISR The ENDISRO and ENDISR1 calls never return to the caller When calling these services the ISR should leave the stack in a defined state so that the following code would perform a correct return to the interrupted context pop ar2 pop arl pop aro popf r11 pop rll pop st reti If no process swap is performed the kernel will actually perform the interrupt exit sequence listed above If the current pr
212. and nanokernel Until now the implementation of VIRTUOSO CLASSICO VSP only uses link ports to com municate between nodes This chapter only covers Virtuoso Classico VSP for SHARC 21 2 SHARC chip architecture This section contains a brief description of the SHARC processor architec ture It is not intended to be a replacement of the Processor s User Manual but as a quick lookup for the application programmer Detailed information can be found in the ADSP 2106x SHARC User s Manual from Analog Devices Inc lt SECTION TO BE COMPLETED PLEASE REFER TO THE SHARC USER MANUAL gt 21 3 Relevant documentation 1 ADSP 2106x SHARC User s Manual Analog Devices Inc 1995 2 ADSP 21000 Family C Tools Manual Analog Devices Inc 1995 3 ADSP 21000 Family Assembler Tools amp Simulator Manual Analog Devices Inc 1995 4 ADSP 21000 Family C Runtime Library Manual Analog Devices Inc 1995 21 4 Version of the compiler Analog Devices Inc has different versions of the G21k compiler In the final release version 3 2d was used 21 5 SHARC silicon revisions We recommend the use of production silicon rev 2 0 and on with Virtuoso Classico VSP Earlier revisions exhibit anomalies that could cause system failures Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 2 1 Virtuoso on the ADSP 2106x SHARC ce a YATIOULNOOD JOSS9001d O I siajjn
213. and netloader 12 1 Host server functionality The host server is a program that does not run on the target but on a host computer e g a PC or workstation It communicates with the target using the available communication mechanism most often a serial line an ISA bus interface or a VME interface Some custom solutions can be more compli cated and communicate between the target and the host computer using intermediate processors ethernet etc The host server is optional when developing programs with Virtuoso as all Virtuoso code is rommable but it greatly helps during the development and maintenance phase The host server provides two main functions 1 Resetting and booting the target 2 Providing runtime I O and executing Remote Procedure Calls The host server is board and host dependent We will use the generic name HOST_X to describe its use Note that on older versions of the software a different syntax for the options maybe in use 12 1 1 Resetting and booting the target The command line syntax is as follows HOST_X options lt network file gt Options are r Reset and set up all boards listed in the network file l Load the executable files on all nodes listed in the network file S Enable server functions If this option is not given the program will terminate after loading the network v Make the program more verbose q Make the program less verbose Z Single node operation no call to
214. ant the actual placement will influence the system s performance As a general rule you are advised to place all semaphores mailboxes and queues on the same processor as the tasks that use them or at least with a minimum of communication distance between them In general it is best to place the queues mailboxes and semaphores on the processors that con tain the receiving tasks Note that you can force the routing a little bit by carefully moving a kernel object to node part of the communication path you want to be used This works well for all command packets however datatransfer always happens using the shortest path If you want to privilege certain data transfers you should assign a higher priority to the message As to the global system configuration best is to keep the main control pro gram centrally located and close to the host server if fast operator interaction or filing on the host system is required In general one can see that system performance will benefit if highly interac tive tasks are grouped together while less interactive tasks are placed more remotely In general this means that computation intensive tasks should be distributed evenly over the system while receiving a lower priority Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 175 Practical hints for correct use 16 5 Note however that this is only a guideline especially as some of the require ments impose a compromise between conflic
215. ap this is kept as an option for the programmer An extra system group has been defined to serve this purpose This task group is called FPU Tasks that require circular buffering should be defined as members of this group in SYSDEF There are some limitations however a i6 and i7 should never be used for circular buffering m6 and m7 are supposed to keep their original values a before calling a kernel service in a task using circular buffering all registers should be set to 0 and m5 m6 m7 m13 m14 and m15 should be set to their default values This is required by the C com piler ADI 2 18 Virtuoso Binding Manual Copyright 1996 Eonic Systems Alphabetical List of nanokernel entry points 22 Alphabetical List of nanokernel entry points e SYNOPSIS e RETURN VALUE In the pages to follow all Virtuoso nanokernel entry points are listed in alphabetical order While some are C callable most of them are not Brief functional description One of the Virtuoso nanokernel service classes of which it is a member The ANSI C prototype C callable or Assembly language calling sequence The return value if any C callable only e ENTRY CONDITIONSReauired conditions before call e EXIT CONDITIONS e DESCRIPTION EXAMPLE SEEALSO e SPECIAL NOTES Conditions upon return of the call A description of what the Virtuoso nanokernel service does when invoked and how a desi
216. at is executing or ready to execute A safe way to ensure this is to restrict the use of KS Abort to aborting the current task The parameter to this task must specify a local task Supplying a remote task will have unpredictable side effects P2 26 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services 11 2 e SUMMARY e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES KS AbortG Abort a task group Task void KS_AbortG K_TGROUP taskgroup The KS_Abort microkernel service is used to abort a task group or a set of task groups in a single call It is an atomic equivalent to calling KS_Abort for every task in the set defined by the argument See KS_ Abort for details NONE K_TGROUP WORKERS K_TGROUP SLAVES abort all tasks in the WORKERS or SLAVES groups 7 KS_AbortG WORKERS SLAVES KS_ Abort KS_ Aborted See the notes under KS_ Abort Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 27 Alphabetical List of Virtuoso microkernel services 11 3 SUMMARY e CLASS ey eas e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO KS Aborted Install abort handler function Task void KS_Aborted void function void The KS_Aborted microkernel service installs an abort handler function for
217. ause it doesn t have a sepa rate identity the producer of the external event another ISR has no means of representing who is waiting for it Note The 21020 is provided with a system stack When an external or a timer interrupt arrives MODE1 and ASTAT are pushed on that system stack The pull operation is performed by the RTI In our version of the kernel MODE1 and ASTAT are always pushed on the stack of the task This is done to be sure that they are saved The ISR level The 21020 has only one ISR level When entering the interrupt handler glo bal interrupts are enabled An interrupt of higher priority can interrupt an interrupt of lower priority An interrupt ends by the nanokernel function ENDISR1 At that point the nanokernel will verify if a process swap is required and allowed The condi tion tested is the logical AND of a NANOK_PRHI 0 The current process is a PRLO process a NANOK_HEAD 0 There is a PRHI process a NANOK_CRIT 0 There are no nested interrupts anymore In case of a swap the interrupt is finished and the PRHI process is swapped in If there are nested interrupts first all interrupts are finished See also the chapter about writing IRQ s for VIRTUOSO CLASSICO and MICRO Communicating with the microkernel As mentioned before the VIRTUOSO microkernel is implemented as a PRHI process It uses a single stack based channel to receive commands from the tasks the ne
218. between clock interrupt service requests The tick value is expressed as a number of high precision clock cycles in the mainx c file Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 9 Virtuoso microkernel types amp data structures 7 8 Memory maps The free RAM in a Virtuoso system may be divided into uniquely identifiable maps A map is addressed via an identifier which is assigned to it during the system generation procedure Each map may be subdivided into any number of blocks of the same size Thus a request for memory from a specific map results in the return of the address of one of the blocks in the map It is of no consequence which block is referenced since all blocks within a map are of equal size A map consists of a set of unused blocks i e free memory and a set of used blocks A map is the structure which Virtuoso uses to manage the memory partition P2 10 Virtuoso Reference Manual Copyright 1996 Eonic Systems Virtuoso microkernel services 8 8 1 8 2 Virtuoso microkernel services Short overview This Section will describe the complete set of the Virtuoso microkernel services The microkernel services are divided into nine classes listed below Task control Semaphores Messages amp mailboxes Queues Timer management Resources Memory management Processor specific Special ON OA BRWDHD Most of the services exist as three variant types depending
219. between the host server program and the DSP96002 target board M3 24 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Motorola 96K DSP 29 15 1 The timer device driver The timer driver is already installed and enabled in procedure main of the examples that accompany the release of the Virtuoso kernel If the timer ISR is installed and enabled the application programmer can read out the timer in high and in low resolution In low resolution the number of kernel ticks are returned As this value is a 32 bit wraparound value it is more interesting to calculate the difference between two values read out consecutively However to facilitate this kernel service KS_Elapse is written for this purpose In high resolution the number of timer counts are returned However if no timer device is present on the DSP96002 application board the timer inter rupts will be generated by the host server program and there is no possibility of reading out the timer counter in high resolution In this case the high reso lution timer value will be equal to the low resolution value The two procedures to read out the timer value are m KS _LowTimer m KS_HighTimer See the Alphabetical List of Virtuoso kernel services earlier in this manual for a full description of these kernel services The timer device driver reserves event signal number 4 for its use 29 15 2 The host interface device driver The host int
220. ble for this purpose PCSTKP equals NANOK_CRIT Symbolic constants for accessing kernel variables and elements of a PCS are defined in the file nanok h Process managment The nanokernel variable are initialized as follows NANOK_PRHI 0 NANOK_HEAD 0 NANOK_TAIL amp NANOK_HEAD NANOK_PRLO amp PCS for IDLE process NANOK_CRIT PCSTKP 0 This means that when an application is started the idle process of the ADI 20 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Analog Devices 21020 DSP nanokernel will start In the current version of the nanokernel all PRHI processes must be created and started by the PRLO process Three steps are required to create a pro cess m create a stack for the process a initialise the PCS a start the process The stack can be placed anywhere in memory It can be a C array of inte gers a memory block allocated by malloc The function _init_process stack stacksize entry i1 i2 is used to initialize the PCS It writes the following values to the first 10 words of the stack PR_LINK link pointer PR_SSTP saved stack pointer R_PIO saved i0 R_PI1 saved il R_PI2 saved i2 _MODE1 saved MODE1 register _ASTAT saved ASTAT register ITS flags END pointer to terminate code ty tg go Wy g vs aA Ww go UJ v W N N 0 g PRUN pointer to ent
221. bles should never be edited 14 4 Task definitions esyntax TASK lt name gt lt node_name gt lt priority gt lt entry_point gt lt taskgroups gt name The name used for reference by the application source code for explicit refer ence to the task in the Virtuoso function calls It is also optionally used by the debugging task node_name The network node the task is residing on e priority we a The priority of the task at boot time The task s priority is a number ranging from 1 highest priority to 64 or 255 lowest priority Equal priorities may be specified e entry point The task entry point is the name of the main routine for the task It follows normal C conventions for function names e stack Size The task stack size in bytes may be defined The default size is 512 bytes Note that an some word oriented 32 bit processors the stack increments in Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 149 System Configuration e taskgroups optional words with 1 word being 4 bytes A task can be part of a taskgroup The following groups are predefined SYS this includes all the tasks that are not blocked when the task level debugger is invoked normally only the debugger task EXE this includes all the tasks that must start up at system initialization FPU this includes all the tasks that use the extended context e g tasks that use the Floati
222. built in circuits that exe cute multiplication and addition in a single clock cycle have multiple buses for parallel data access and have DMA and or communication hardware on the chip The combination of all these features imposes quite a challenge to the software environment especially in the context of the use of a C compiler that was not always thought out with these demands in mind Most real time kernels operate at the C level only and have an unacceptable overhead for handling the high demands on DSPs The Virtuoso system has solved this problem by introducing an open four level support that tries to manage the context as a resource trading in performance for flexibility but only when the application needs it at a certain point Copyright 1996 Eonic Systems Virtuoso User Manual P1 21 Functional support from Virtuoso 4 5 4 6 A first conclusion The real benefit from the use of Virtuoso is that it optimizes the use of the resources in this case mainly the processor in a way that is fairly indepen dent of the processor technology A question remains how does one design an application with a real time kernel The answer is that real time kernels have evolved because practice has shown what services a real time kernel should provide This means that one divides up the application into tasks that interact by different methods Most interactions can be classified as signals event flags and communica tion
223. c KS_InqMap Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 29 Alphabetical List of Virtuoso microkernel services 11 5 e SUMMARY e CLASS es es ee e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO KS _ AllocW Allocate a block of memory with wait Memory management int KS_AllocW K_MAP map void block The KS_AllocW microkernel service is used to allocate a block of memory from a predefined memory map If the map is empty the calling task is put on a priority ordered waiting list and is descheduled until a block becomes avail able RC_OK typedef void MyBlock MyBlock p K_MAP MAP1K int RetCode RetCode KS_AllocW MAP1K amp p if RetCode RC_OK printf Cannot allocate memory n KS_Alloc KS_AllocWT KS_Dealloc KS _ DeallocW KS_DeallocWT P2 30 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services 11 6 e SUMMARY e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO KS_ AllocWT Allocate a block of memory with timed out wait Memory management int KS_AllocWT K_MAP map void block K_TICKS ticks The KS_AllocWT microkernel service is used to allocate a block of memory from a predefined memory map If the map is empty the calling task is descheduled and put on a priority ordered waiting list I
224. c Systems Virtuoso on the Motorola 96K DSP 29 7 Alphabetical list of ISR related services Fkernel_sign_entry for entering the kernel from within an ISR single processor version only KS KS for removing an KS _EventW EnableISR for waiting on an interrupt at the task level for installing an ISR _DisableISR ISR Copyright 1996 Eonic Systems Virtuoso Binding Manual M3 19 Virtuoso on the Motorola 96K DSP 29 8 1 Fkernel_sign_entry Synopsis Label jumped to when entering the kernel from within an ISR e Brief ocrais ci em This service gives a signal to the kernel with an event code numbered between 0 and 63 inclusive A task can wait on the occurrence of such a sig nal by using kernel service KS_EventW n Example Seealso KS_EventW e Special Notes The kernel signalling service assumes that certain conventions are followed by the ISR 1 Stack Pointer R7 must be incremented at the very start of the ISR 2 Registers DO L D1 L and RO have to be saved at the start of the ISR after the prior increment of R7 with the sequence as indicated see also previous paragraph 3 Prior to jumping to the entry Fkernel_sign_entry register DO L must be loaded with the event number between 0 and 63 inclusive 4 A JMP instruction must be used to jump to the entry Fkernel_sign_entry not a JSR instru
225. call has no effect e RETURN VALUE NONE EXAMPLE K_TIMER xtimer4 K_SEMA MySema timer4 KS_AllocTimer signal MySema after 100 ticks and then every 20 ticks ar KS_StartTimer timer4 100 20 MySema KS_StopTimer timer4 no more signals to MySema now mf SEEALSO KS_StartTimer Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 101 Alphabetical List of Virtuoso microkernel services 11 64 e SUMMARY e CLASS es es ea e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO KS Suspend Suspend execution of a task Task void KS_Suspend K_TASK task The KS_Suspend microkernel service causes the specified task to be placed into a suspended state The suspended state will remain in force until it is removed by a KS_Resume or KS_ Abort microkernel service A task may suspend itself NONE K_TASK DETECT KS_Suspend DETECT suspend task DETECT KS_Suspend KS_TaskId suspend myself KS_SuspendG KS_Resume KS_ResumeG P2 102 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services 11 65 e SUMMARY e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO KS SuspendG Suspend execution of a group of tasks Task void KS_SuspendG K_TGROUP group The KS_SuspendG microkerne
226. cally when make is invoked To rebuild everything make will start by pre processing the sysdef file and running sysgen This will generate a C source file nodel c and two headers nodel h and allnodes h The nodel c file contains configuration code in C for one node and the header files are to be included into the users code in order to access kernel objects None of these files should be edited by hand Once the application is built it may be run using the net loader and host server as follows boardhost rls hello The name of the server is target specific as is the file in this case hello nli which specifies the mechanism of loading the target hardware However when the program runs the expected greeting should appear on the screen whatever system is used Copyright 1996 Eonic Systems Virtuoso User Manual P1 43 Simple Examples As it is designed for real time applications which normally run continuously there is no facility to terminate a Virtuoso program so hit CTRL C or CTRL BREAK and press X to get back to the operating system prompt 5 2 Use of a Queue The above example does not show how tasks interact using the microkernel objects In this example a sender task sends a message to a receiving task via a queue To make things more interesting the two tasks are placed on different processors The sysdef file is as follows NODE NODE1 C40 NODE NODE2 C40 NETLINK NODE1 NetLinkDma 4 P
227. can be of use while recovering from a system error e RETURN VALUE NONE EXAMPLE K_SEMA DeviceReady KS_ResetSema DeviceReady reset semaphore KS_Wait DeviceReady and wait on it SEEALSO KS_ Signal KS_Wait Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 81 Alphabetical List of Virtuoso microkernel services 11 46 e SUMMARY e CLASS es ey eae e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO KS ResetSemaM Reset a list of semaphores Semaphore void KS_ResetSemaM K_SEMA semalist The ResetSemaM microkernel service performs like the KS_ResetSema microkernel service except that it operates on a semaphore list A sema phore list is an array of semaphores terminated by the predefined constant ENDLIST This microkernel service reduces the number of Virtuoso micro kernel service operations needed when multiple semaphores must be reset NONE K_SEMA event K_SEMA semalist SWITCH1 SWITCH2 SWITCH3 ENDLIST KS_ResetSemaM amp semalist forget switch history event KS_WaitM semalist wait for switches KS_ResetSema KS_ Signal KS_SignalM KS Wait KS _WaitM P2 82 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services 11 47 e SUMMARY e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE
228. ccessed as a word operand but not all 8 bits are defined m the LC Loop Counter LA Loop Address Register SSH System Stack High and SSL System Stack Low registers are 16 bits wide and may be accessed as word operands When used as a source operand these registers occupy the low order portion of the 24 bit word the high order portion is zero When used as a destination oper and they receive the low order portion of the 24 bit word and the high order portion is not used The Loop Counter Register is a special 16 bit counter used to specify the number of times a program loop is to be repeated The Loop Address reg ister indicates the location of the last instruction word in a hardware program loop The System Stack is a separate internal memory divided into 2 16 bit wide parts each 15 locations deep The SSH stores the PC contents and the SSL stores the stores the SR contents for subroutine calls and long interrupts In order to be able to use this hardware stack and the associated commands hardware DO loops in a multitasking environment it is saved along with other registers to the user stack of the calling task when this is swapped out This way no conflicts can occur if the next task also makes use of the hard ware stack Copyright 1996 Eonic Systems Virtuoso Binding Manual M1 3 Virtuoso on the Motorola 56K DSP The SP Stack Pointer register is a 6 bit register that may be accessed as a word operand I
229. ce Manual Copyright 1996 Eonic Systems Runtime libraries int vsprintf char s const char format va_list vargs 13 2 PC graphics I O 13 2 1 Overview From version 1 2 on an optional graphical server is included The distributed graphics server introduced with version 1 2 enables you to perform graphics operations on the PC screen from any task on any processor in the system The interface is not designed for heavy duty graphics work but will be useful in many applications e g to provide an attractive human interface The graphics server works as follows 1 Application tasks use the function calls defined in GRINT C These functions format your data into command packets that are send to a graphics driver task 2 Two queues GRAPHOQ and GRAPHIQ establish the system wide connection between the application tasks and the driver task 3 The driver task GRAPHDRY executes on the root processor and communicates with the host PC server program GRAPHDRV should run at fairly high priority normally just below the console drivers 4 The PC server program has been recompiled with the Borland C compiler and is extended to interface to the Borland BGI drivers These drivers do the actual plotting on the screen The extended server is fully compatible with the standard version and you can use it to run the compiler tools as well The two queues must be protected by a resource named GRAPHRES This is necessary fo
230. cess communication e SYNOPSIS PRHI_SIG PRHI_SIG is defined in macro h e DESCRIPTION Ifa process is waiting on the channel it is rescheduled put at the tail of the process FIFO Otherwise the event count is incremented In either case control returns to the caller e ENTRY CONDITIONS i4 pointer to channel e EXIT CONDITIONS r0 rl r2 are corrupted All other registers are preserved EXAMPLE include macro h i4 dm SYNC_CHAN PRHI_SIG SEEALSO PRHI WAIT e SPECIAL NOTES This entry point must not by called from the low priority context but it can be used by interrupt handlers ADI 44 Virtuoso Binding Manual Copyright 1996 Eonic Systems Alphabetical List of nanokernel entry points 19 14 a gt a S ce ee ee e CLASS 2 Saw es e SYNOPSIS e DESCRIPTION e ENTRY CONDITIONS e EXIT CONDITIONS e EXAMPLE SEEALSO e SPECIAL NOTES PRHI_WAIT Consume an event from a signal channel or deschedule Process communication PRHI_WAIT PRHI_WAIT is defined in macro h If the event counter is not zero it is decremented an control returns to the caller If the event counter is zero the calling process is swapped out and set to wait on the channel It will be rescheduled by the next call to the PRHI_SIG service on the same channel i4 i0 r0 rl r2 are corrupted include macro h wait for event on SYNC_CHAN i4 dm SYNC_CHAN
231. cessor boards in the node and the file system of OS 9 the text output on the console screen and the keyboard input Following list of features are supported by the server program 1 loading an application including the Virtuoso kernel from disk and putting it on another processor board via the VME bus At startup time the target pro cessor board has no operating system running on it and has only a system level debugger in its EPROM s 2 starting a target processor board that has just received its application soft ware from the server program This can be achieved by use of the interrupt vector of the VME mailbox that is present on a processor board of CompCon trol 3 on request of an application running on another processor board putting characters on the console screen 4 catching key presses from the keyboard and sending the key code to the tar get processor board 5 on request of an application running on another processor board performing standard Input Output functions hereby eventually accessing the file system Communication between the server program and target processor boards will be done via the VME mailboxes on the processor boards by the use of an Eonic Systems proprietary communication protocol Source files for the server program Following source files have to be present in the source directory of the server program in order to be able to make an executable server c C source file of the server prog
232. cessors are very bad at the inter rupt response level The key is to develop smarter algorithms to solve the problem In the past this has been done with programming constructs like super loops In a super loop all possible events are polled in a large loop each branch of the loop then handling the event While this approach can solve some soft real time applications it is not very flexible as a single change to the system can require a complete review of the program as the whole program s timing behavior is affected For hard real time problems this means that the processor load had to be kept low so that in most cases an acceptable performance can be obtained P1 20 Virtuoso User Manual Copyright 1996 Eonic Systems Functional support from Virtuoso Things changed when people started to realize that the best thing to do is to model the real world problem more directly The problem at hand can very often be described by determining the different functions and agents of the system The better algorithms then map each function into a so called task and provide the capability to give the processor to the task that needs it most so called preemptive scheduling as it enables that a given task is pre empted in order to switch to another task This implies the use of a crite rium in this case the assignment of a priority to each task A task is to be considered as an independent unit of execution that interacts with other tasks or wit
233. chnical reasons dictated syntax changes Refer to your interface libraries for a cor rect definition of the syntax and the read me files Eonic Systems International makes no warranty expressed or implied with regard to this material including but not limited to merchantability or fitness for a given purpose The information in this document is subject to change without notice Eonic Systems International assumes no responsibility for any errors which may appear herein Eonic Systems International shall have no liability for compensatory special incidental consequential or exemplary damages This document may not be copied in whole or in part without the express written permission of Eonic Systems International The products described in this document are and shall remain the property of Eonic Systems Inter national Any unauthorized use duplication or disclosure is strictly forbid den Copyright 1996 Eonic Systems Virtuoso User Manual INT 5 Trademark Notices Trademark Notices Virtuoso is a trademark of Eonic Systems Inc 12210 Plum Orchard Drive Silver Spring MD 20904 Tel 301 572 5000 Fax 301 572 5005 e mail info eonic com For support support eonic com WEB http www eonic com Europe Nieuwlandlaan9 B 3200 Aarschot Belgium Tel 32 16 62 15 85 Fax 32 16 62 15 84 Copyright 1996 Eonic Systems Inc Virtuoso Nano is a trademark of Eonic Systems Inc Virtuoso Micro is a t
234. cktime et 10000 printf FORMAT average lock and unlock resource et KS_Sleep 250 KS_Elapse amp et for i 0 i lt 5000 i MaplMemorymap AllocW amp p Map1Memorymap Dealloc amp p et KS_Elapse amp et et ticktime et 10000 printf FORMAT average alloc and dealloc memory page KS_Sleep 250 void hiqtask void int i for i 0 i lt 1000 i Demoqx1Queue DequeueW text2 1 for i 0 i lt 1000 i Demoqx1Queue DequeueW text2 4 void himtask void int i size KMessage Message Message tx_task ANYTASK Message rx_data text2 Message size 0 for i 0 i lt 1000 i Mailbox1 ReceiveW Message for size 8 size lt 4096 size lt lt 1 Message size size for i 0 i lt 1000 i Mailbox1 ReceiveW Message et P2 196 Virtuoso Reference Manual Copyright 1996 Eonic Systems Microkernel C interface testl cpp void histask void LAG GE K_SEMA slist 5 slist 0 SEMI slist 1 SEM2 slist 2 ENDLIST slist 3 ENDLIST slist 4 ENDLIST for i 0 i lt 1000 i Semaphorel Wait for i 0 i lt 1000 i Semaphorel WaitT 5000 for i 0 i lt 1000 i KS_Wait slist for i 0 i lt 1000 i KS_WaitMT slist 5000 slist 2 SEM3 for i 0 i lt 1000 i KS_Wait SLis
235. code modules a asingle low priority process PRLO process m any number of high priority processes PRHI process m any number of interrupt handlers It is important to understand what exactly is meant by a process A process is a thread of execution that has both an identity and a private workspace These two properties logically equivalent make it possible for a process to be swapped out and wait for an external event while another process is allowed to continue Interrupt handlers in contrast do not have a private workspace The PRHI processes are scheduled in strict FIFO order and must observe the special register conventions mentioned above The PRLO process is assumed to be a C function using the compiler register conventions and must always be ready to execute You can compare it with the IDLE task of the microkernel All communication inside the nanokernel is performed using channels Sev eral types exit The simplest type is used for synchronization and corre sponds to a counting semaphore The other types are used for data transfer The possibility is provided that a user can add his own channel types The microkernel managing the tasks is built as an application on top of the nanokernel The main component is a PRHI process that executes com mands it receives from a channel When the channel is empty the microker nel looks for the next task to run replaces the nanokernel IDLE process by that task and performs th
236. common memory The only require ment is a correctly working driver The syntax of a NETLINK definitions is e syntax NETLINK lt nodel gt lt driverl gt lt connector gt lt node2 gt lt driver2 gt e node1 node2 The two connected nodes e driver1 driver2 The drivers used on the respective nodes connector The lt connector gt can be bidirectional link gt unidirectional link from left to right P2 146 Virtuoso Reference Manual Copyright 1996 Eonic Systems System Configuration e example lt unidirectional link from right to left Note that the driver description between quotes must be syntactically correct as it is copied literally into the nodex c file by sysgen The separator symbol is defined as follows NETLI ROOT NK NODE2 Net Link_Driver 1 bidirectional link between ROOT and NOD NETLI ROOT Unidirectional NETLI ROOT N NOD ETLI E3 DRI NK Net link_Driver 2 gt NODE3 NetLinkD C3 PR TO_DMA link between ROOT and NO NK Net link_Driver 2 lt NODE3 NetLinkD 0 PRIO_DMA NK Net LinkDma 1 PRIO_ALT Net LinkDma 4 PRIO_A ER ROOT ER NODE4 RawLinkDma NODE LT 4 5 PRIO_DMA PRIO_DMA RawLi
237. crokernel services 11 49 e SUMMARY e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO KS ResumeG Resume a task group Task void KS_ResumeG K_TGROUP taskgroup The KS_ResumeG microkernel service clears the SUSPENDED state of a task group It is equivalent to calling KS_Resume for every task in the speci fied groups but guarantees that the operation is performed as a single atomic action NONE K_TGROUP DEVICES KS_ResumeG DEVICES resume all device drivers KS _ResumeG KS Suspend KS _SuspendG Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 85 Alphabetical List of Virtuoso microkernel services 11 50 e SUMMARY e CLASS es es ee e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO KS Send Send a message to a mailbox Mailbox int KS_Send K_MBOX mbox K_PRIO prio K_MSG msg The KS_Send microkernel service inserts a message into the mailbox in order of the indicated priority If the receiver used a valid pointer as the desti nation address the microkernel initiates a data copy operation limited to the smallest of the message sizes indicated by the sender and receiver At the end of the datacopy the sending task is rescheduled If the rx_task field in the K_MSG was set to the predefined constant ANYTASK the first receiver of the waiting list with a matching s
238. ction install_my_isr is called to initialize the command packet and install the ISR Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 27 Virtuoso on the Analog Devices 21020 DSP 18 10 12 K_ARGS CP1 CP1P K_SEMA SLIST1 SEMA1 SEMA2 ENDLIST extern void my_isr void void install_my_isr create a pointer to the command packet CP1P amp CP1 initialize CP1 for a KS_Signal SEMA1 service CP1 Srce 0 CP1 Comm SIGNALS CP1 Args sl sema SEMAI or for a KS_SignalM SLIST1 service CP1 Scre 0 CP1 Comm SIGNALM CP1l Args sl list SLIST1 install the ISR KS_EnableISR my_isr For the ISR something like the code listed below will be required extern _CP1P extern _K_ArgsP global _my_isr _my_isr i4 dm _K_ArgsP i4 contains pointer to channel r2 dm _CP1P r2 contains data PRHI_PSH signals semaphore Virtuoso drivers on the 21020 Drivers are the interface between the processor and peripheral hardware and the application program They normally serve two purposes data com munication and synchronization As polling is not a recommended practice in a real time system most drivers will use interrupts in one way or another The virtuoso system does not provide a standard interface to drivers this ADI 28 Virtuoso Bindin
239. ction The System Stack of the processor will be managed by the kernel so that when returning from interrupt the correct program address will be loaded in the Pro gram Counter This kernel service is only callable from an ISR written in assembly when used with the single processor version with no nanokernel M3 20 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Motorola 96K DSP 29 9 2 KS DisablelSR BRIEF Disables to ISR to be triggered by interrupt SYNOPSYS void KS_DisableISR int IRQ e DESCRIPTION This C callable service disables an ISR by writing an ILLEGAL instruction at the appropriate place in the interrupt vector table Also for the following inter rupts the corresponding bits in the IPR register of the processor will be changed accordingly IRQA IRQB IRQC DMA Channel 1 DMA Channel 2 Host A Command Host B Command Other interrupts can also be disabled by this service but only in the sense that the JSR instruction at the corresponding place in the interrupt vector table will be overwritten by an ILLEGAL instruction e RETURN VALUE NONE EXAMPLE KS_DisableISR 9 Seealso KS_EnableISR e Special notes Copyright 1996 Eonic Systems Virtuoso Binding Manual M3 21 Virtuoso on the Motorola 96K DSP 29 10 3 e BRIEF sia Boe SYNOPSYS e DESCRIPTION e RETURN VALUE EXAMPLE
240. ctor During an interrupt instruction fetch instruction words are fetched from the interrupt starting address and interrupt starting address 1 locations While these two interrupt instructions are being fetched the Program Counter is inhibited from being updated and so the interrupt instructions are just inserted in the normal instruction stream Two types of interrupt routines may be used fast and long The fast routine consists of only the two automatically inserted interrupt instruction words A jump to subroutine within a fast interrupt routine forms a long interrupt A long interrupt routine is terminated with an RTI instruction to restore the PC and SR from the System Stack and return to normal program execution Copyright 1996 Eonic Systems Virtuoso Binding Manual M3 9 Virtuoso on the Motorola 96K DSP 29 4 Relevant documentation 1 2 DSP96002 IEEE Floating Point Dual Port Processor User s Manual Motorola Inc 1989 Intertools Toolkit User s Manual 96002 Release 1 1 for the PC Inter metrics Inc 1991 Document Version 3 7 C Compiler Assembler Version 1 1 29 5 C calling conventions and use of registers This section contains following topics Storage Allocation Segmentation Model Register Usage Subroutine Linkage Stack Layout 29 5 1 Storage Allocation The basic C data types are implemented as follows char 32 bits unsigned short 32 bits signed int 32 bits signed unsigned
241. cuting immediately This call returns when the started process deschedules or terminates e RETURN VALUE none EXAMPLE int wsp1 100 int wsp2 100 extern void procl void extern void proc2 void int N 1000 _init_process wspl procl 0 N _init_process wsp2 proc2 0 N _start_process wspl _start_process wsp2 SEEALSO _init_process e SPECIAL NOTES This function cannot be used from within a high priority nanokernel process It must be called from the C main function or by a microkernel task only TI2 24 Virtuoso Binding Manual Copyright 1996 Eonic Systems Alphabetical List of nanokernel entry points 38 3 SYNOPSYS e DESCRIPTION ENDISRO Terminates a level 0 ISR and conditionally invokes the process swapper Interrupt service management LATcond ENDISRO ENDISRO is defined in TRAPS INC This is the normal way to terminate an ISR running at level O global inter rupts disabled It must be called if the ISR has previously used any nanoker nel service that can reschedule a process e g PRHI_SIG If the ISR did not interact with the kernel a normal ISR exit sequence popping saved regis ters and RETI can be used instead A nanokernel process swap will be performed IFF m the calling ISR interrupted the nanokernel low priority process m a high priority process is ready to execute e ENTRY CONDITIONS The ISR should have saved the interrupted context so that
242. data is available This signalling causes the waiting task to resume presumably to process the input data Mailboxes Mailboxes are the means by which data can be transmitted synchronously from a sender to a receiver task The actual message acts as a request for a data transfer between a sender and a receiving task The data referenced by the message may contain whatever is required by the receiver task and in whatever format A mailbox acts as a meeting place for tasks wishing to exchange a message or the data referenced by it It maintains two waiting lists one for senders and one for receivers When a new send or receive request arrives the mailbox searches one of the lists for a corresponding request of the other type If a match is found it is removed from the waiting list and the data transfer is started When this has finished both tasks are allowed to resume execution If no match can be found the caller is suspended and put on a waiting list or the operation fails The message is implemented using a datastructure that contains following elements The size of the referenced data the pointer to the data at sender s side the pointer to the data at receiver s side the sending task the receiving task the info field optional oa fF WO ND P2 6 Virtuoso Reference Manual Copyright 1996 Eonic Systems Virtuoso microkernel types amp data structures The sending task will fill in following
243. de regis Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 9 Virtuoso on the Analog Devices 21020 DSP ters of the interrupted program The four external interrupts and the timer interrupt automatically push ASTAT and MODE1 onto the status stack These registers are automatically popped from the status stack by the inter rupt return instruction RTI 18 4 8 USTAT The User Status Registers USTAT1 and USTAT2 are general purpose reg isters that can be used for user status flags These system registers are set and tested using system instructions 18 5 Relevant documentation 1 ADSP 21020 User s Manual Analog Devices Inc 1991 2 ADSP 21000 Family C Tools Manual Analog Devices Inc 1993 3 ADSP 21000 Family Assembler Tools amp Simulator Manual Analog Devices Inc 1993 4 ADSP 21000 Family C Runtime Library Manual Analog Devices Inc 1993 18 6 Version of the compiler Analog Devices Inc has different versions of the G21k compiler We used version 3 0 18 7 Runtime Environment This section contains following topics a Data types a Architecture file Runtime header 18 7 1 Data types The ADSP 21020 can process 32 bit operands with provisions for certain 40 bit operations The arithmetic types supported directly are listed below All other arithmetic data types are mapped onto these types m type float IEEE 754 standard single precision floating point It
244. definition and includes but is not limited to magnetic optical Read Only Memory of all sorts and Random Access Memory Copyright 1996 Eonic Systems Virtuoso User Manual LIC 1 License agreement 3 3 OBJECT CODE is any form of the Licensed Product not included in the definitions of SOURCE CODE or EXECUTABLE CODE above including but not limited to object code files and object code libraries on any medium 3 4 SITE is any single designated place of business where the Licensed Product will be used by Customer in the development of Customer s applica tion The SITE is limited to a single building or department or group of license users but Eonic Systems may at its sole discretion determine what shall constitute the SITE 4 CUSTOMER S PRIVILEGES Regarding the Licensed Product the Customer may 4 1 Use any representation of the Licensed Product on one development station at the Customer s SITE 4 2 Copy the Licensed Product for backup or archival purposes and to sup port Customer s legitimate use of the Licensed Product 4 3 Merge or otherwise combine the Licensed Product in part with other works in such a fashion as to create another work agreeing that any portion of the Licensed Product so merged remains subject to the terms of this Agreement Whenever the source code of the Licensed Product is changed during the work CUSTOMER shall consult Eonic Systems to verify if the changes are within the boundaries of the Lic
245. der discussion On some common processors characters are stored one per word or sizeof does not give the number of 8 bit bytes in a type On these processors the examples may need modification where a size parameter or structure is used List of related Virtuoso microkernel services that could be examined in con junction with the current Virtuoso microkernel service Specific notes and technical comments Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 25 Alphabetical List of Virtuoso microkernel services 11 1 SUMMARY e CLASS ey eas e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES KS Abort Abort a task Task void KS_Abort K_TASK task The KS_ Abort microkernel service is used to abort a task s execution If the task has no abort handler it will terminate execution immediately otherwise the abort handler function is executed using the identity and priority level of the aborted task NONE K_TASK WORKTASK KS_Abort WORKTASK abort task WORKTASK KS_Abort KS_TaskId abort the current task KS_AbortG KS_Aborted Be very careful when using this service as the microkernel does not clean up the current state It is illegal to abort a task while it is blocked in a waiting kernel service The task is not removed from the waiting list of the object This means that KS Abort should only be used on a task th
246. des As a result source code of applications developed on the single processor version can be reused without any modification 4 11 Target Environment The standard support package of Virtuoso is designed to mostly operate in an embedded or semi embedded processor environment Over the life of the system the application will be mostly static The processor may be a single board microcomputer a personal computer a minicomputer or a large multi processor system No assumptions are made about the configuration of the target system It is the responsibility of the user to define the target environ ment and to insure that all necessary devices have program support User interfaces can be built with the I O and graphics library that has to be used with a server program on a host computer e g a PC or UNIX workstation 4 12 Virtuoso auxiliary development tools Before programming the application the first thing done after a functional analysis is to translate the results of the analysis into the terms understood by the system generation utility of Virtuoso The result is the sysdef text file in which the structure of the application tasks semaphores topology etc Copyright 1996 Eonic Systems Virtuoso User Manual P1 37 Functional support from Virtuoso 4 13 is specified using a simple syntax This file acts as a specification tool and as a maintenance tool It is part of the system because in order to change an attribute of
247. diff2 K_SEMA SWITCH void KS_Elapse amp timestamp determine reference time KS_TestW SWITCH wait for event diffl KS_Elapse amp timestamp time since first call KS_TestW SWITCH wait for event diff2 KS_Elapse amp timestamp time since second call SEEALSO KS_LowTimer KS_HighTimer P2 40 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services 11 15 e SUMMARY e CLASS oe Saw es e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e Special Notes KS EnablelSR Install an interrupt service routine Processor specific int KS_EnableISR int IRQ void ISRO void The KS_EnablelSR microkernel service provides a safe way to install an interrupt service routine The operation may fail if the interrupt is already enabled Any previously installed handler should be removed first using KS_disablelSR An ISR can operate entirely in the background or it can pass the interrupt on to a waiting task by generating an event RC_OK or RC_FAIL extern void ADC_ISR void if KS_EnableISR 4 ADC_ISR RC_OK printf Unable to install the ADC ISR n KS_DisablelSR KS_EventW Part 3 of this manual This service is processor specific and the prototype may vary between pro cessors This service does not actually enter the microkernel and therefore cannot
248. ding and receiving tasks are running on the same pro cessor The user must explicitly indicate that he wants it otherwise 3 All stages of the message mechanism are prioritized a high priority message is never forced to wait while a lower priority operation occu pies the network resources Synchronous operation enables the kernel to defer the actual copying of the data until both sides are ready for the transfer As a result itis not possible to flood the network buffers with messages that nobody wants to receive Always passing messages by value facilitates the design of user code that will work on any node If a copy of the message data is made the receiver is free to specify the exact destination of the data If only a pointer is passed the receiving task has no such choice and special code will be needed to handle this situation In many cases a copy would still be required for the receiver to function correctly Both features also cooperate to ensure that correct behavior of an applica tion does not depend on the hidden sequentialisation which is imposed when sender and receiver are on the same node It is still possible to pass messages by reference if your application demands it This however has to be done explicitly In this way the use of a node dependent operation is clearly documented in the source code In many applications the message system will be the primary user of the net work resources In these c
249. dseg SEEALSO e SPECIAL NOTES A normal interrupt exit popping saved registers and RETI is not allowed for an ISR running at level 1 ADI 34 Virtuoso Binding Manual Copyright 1996 Eonic Systems Alphabetical List of nanokernel entry points 19 4 K_taskcall BRIEF Sendacommand packet to the microkernel process CLASS Process communication e SYNOPSYS void K_taskcall K_ARGS A e DESCRIPTION This C callable function is used by all KS_ services to send command pack ets to the microkernel process e RETURN VALUE none EXAMPLE SEEALSO PRLO_PSH e SPECIAL NOTES This function must be called by microkernel tasks only Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 35 Alphabetical List of nanokernel entry points 19 5 e BRIEF scape Sas e GLASS ee eos ee SYNOPSYS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES KS_DisablelSR Remove an ISR from the interrupt vector table Interrupt service management void KS_DisablelSR int isrnum This C function is equivalent to KS_EnablelSR isrnum NULL The interrupt is disabled and the corresponding entry in the interrupt vector table is cleared none KS_DisableISR 8 remove the host interrupt KS _EnablelSR Interrupt numbers are 0 31 for interrupts enabled in the IRPTL register ADI
250. ducts are available in three different implementations SP Single Processor implementation These implementations do not assume the presence of any other processor in the system The Virtuoso kernel provides multi tasking with preemptive scheduling MP Single Processor implementation with multi processor extensions The multi processor extensions enable fast and easy interprocessor commu nication all in about 500 instructions With minimum set up times it provides for maximum performance by using the DMA engines when available Com munication is point to point between directly connected processors VSP Virtual Single Processor implementation The true solution for parallel processing is to implement the communication as part of the kernel service hence providing fully transparent parallel pro cessing The VSP implementation provides this feature by way of fully dis tributed semantics permitting to move kernel objects and or changes to the target topology without any changes to the source code The current product offerings are as follows Virtuoso Nano is based on the core nanokernel of the Virtuoso product range It can be very small 200 instructions but is ultrafast It provides for true multitasking and interprocess communication services The VSP imple mentation is still not larger than 1000 instructions Virtuoso Micro features a small but fast microkernel that provides preemp tive scheduling for a number of priori
251. e implemented as low priority processes while these tasks can communicate among each other via the kernel running at high priority For this reason Virtuoso contains some transputer specific calls such as KS_linkinW and KS_LinkoutW On the other hand if within a user defined task of a given priority several processes that communicate with each other are started the transputer hardware still takes care of the linked list continuity The final result is that at each priority level the normal inter process communication facilities are available This is primarily of interest as it simplifies the software design The kernel itself is not resident but forms an integral part of the application program that is linked with the task code As such a system designed with Virtuoso exhibits a two layer structure At the highest level each task has an unique priority while at the lowest level the basic hardware supported transputer mechanisms are still available Figure 3 gives a schematic overview of Virtuoso running on a single transputer Note that during program development there is little difference for the pro grammer as to writing normal applications on the transputer This is achieved by way of a system generation utility that generates automatically all kernel tables based on the information provided by the programmer Copyright 1996 Eonic Systems Virtuoso Binding Manual T8 7 Virtuoso on the INMOS T2xx T4xx T8xx 33 9 33 10
252. e the latter being partic ularly important for real time applications Virtuoso is not only used for single processor applications For those appli cations requiring more than one processor the tasks can communicate with other connected processors using the communication drivers included with the MP implementations The VSP implementations of Virtuoso also provide support to execute fully transparently remote microkernel services from within different processors permitting to consider the whole network of pro cessors as a virtual single processor system The system definition file that is parsed by Sysgen contains all the hardware dependent information and effectively shields the application from the underlying hardware For debugging and fine tuning Virtuoso is delivered with a task level debug ger and tracing monitor The use of these tools will help you in debugging the system as well as optimizing its performance If as a result tasks or other objects are moved to other processors the only work to do is to change the system definition file regenerate the system tables and recompile the appli cation Developing applications with Virtuoso can be as easy as developing P1 8 Virtuoso User Manual Copyright 1996 Eonic Systems A short introduction any other application under straight C IMPORTANT NOTE Nevertheless please read the manual before you start writing your pro grams 2 2 Underlying assumptions when programming
253. e 1 so that an applica tion task can wait on it by using kernel service KS_Event with parameter value 1 After being awaken from an event signal 1 the application task can get the information with kernel service KS_Linkin The information that is read is formatted in the Eonic Systems proprietary protocol During a mailbox exception handle the exception handler will lock the mail box to prevent accidentally overwriting by processes on other boards This locking is done by writing a non zero value at a fixed address 0x08000080 Other processor boards or the server program on the main processor board willing to use the mailbox will therefore have to check the value at this address prior to write information in the mailbox Only if the value is zero the mailbox is free to be written in timerl a The timer interrupt routine works on interrupts coming from the DUART on the processor board The DUART is programmed as a timer to give regular interrupts each 1 millisecond The system level debugger present in the EPROM s of the processor board can be consulted by pushing the abort button on the front of the processor board This however can be done only once because the system level debugger will stop the timer actions of the DUART It is not possible to return from the system level debugger to the application by entering the command g of the debugger as the application is completely paralyzed The proces sor board
254. e KS_Nop call is only there for benchmark reasons while the KS_User permits the application program mer to run a function at the same priority of the microkernel The latter one must be used with caution as it disables preemption during the execution of that critical function 4 7 10 Class Processor Specific Today s processors often have a number of additional features or peripheral device support built in on the chip Because most of these are different from processor to processor we have listed them here These include the capa bility to measure time with a high precision and hence the capability to mea sure precisely the CPU workload Other microkernel services provide Copyright 1996 Eonic Systems Virtuoso User Manual P1 33 Functional support from Virtuoso support to use the communication ports of the chips in an easy way Finally Virtuoso also provides low level support for enabling and disabling interrupts so that a Task can wait on an Event that is generated by the Interrupt Service Routine As most of these features are close to the hardware see the next paragraph for more details 4 8 Low level support with Virtuoso The unit of execution of Virtuoso is the task The coordination of Virtuoso tasks by the various objects permit a high level design of the application independent of the actual target processor the application is running on From the viewpoint of the programmer the task is a fairly large unit of e
255. e KS_SetPrio microkernel service or dynamically by the microkernel Task group set Each task can be part of a number of task groups The task group set is a 32 bit word of which each bit represents a task group The existence of task groups and the related microkernel services permit task operations in a single atomic action Task State Whenever the Virtuoso microkernel is looking for a task to execute it examines the execution state variable to see if the task is runable or not The execution state is contained in a single word and a value of 0 zero indicates that the task is runable Whenever the task state is different from zero this indicates that the task is suspended waiting or aborted A task normally becomes runable after it has been started Once runable the task will become active if it has the highest priority of all runable tasks A task becomes not runable if it is suspended or if it issues a microkernel P2 4 Virtuoso Reference Manual Copyright 1996 Eonic Systems Virtuoso microkernel types amp data structures 7 2 4 7 2 5 7 2 6 7 2 7 7 3 service that cannot be serviced immediately hence waiting When suspended a task can only become runable again by a KS_Resume service call Normally a task only terminates when it reaches the end of its execution thread Tasks can be aborted independently of their current point of execution by a KS_Abort service call Once aborted the task can only
256. e Manual P2 157 Debugging environment under Virtuoso Waiting for Semailist Waiting for Resource Waiting for Allocation Waiting for Network 15 2 6 Queues Waiting on return of KS_WaitM T Waiting on return of KS_ Lock Waiting on return of KS_Alloc W Waiting for network reply transient state This command produces a snapshot of the queues in the system as shown below Six columns are used in the snapshot Name the queue s symbolic name Neurr the current number of entries in the queue Nmax the maximum number of entries ever been in use Size the queue size as defined at system generation Count the number of times the queue was enqueued or dequeued Waiters a list of waiting tasks to enqueue or dequeue The Queue snapshot appears as gt q QUEUE STATES Name Level Nmax Size Count Waiters CONIQ 0 0 32 J CONOQ 0 121 256 732 CONODRV DEMOQX1 0 953 4 45 QUEUETST DEMOQX4 0 1000 8 87 15 2 7 Semaphores The semaphores state are represented in four columns Name the semaphore s symbolic name Level the current level value of the semaphore Count the total number of times the semaphore was signalled Waiters the tasks waiting on the semaphore to be signaled gt S SEMAPHORE STATES Name Level Count Waiters SEMO 0 123 TEST1 SEM1 0 0 P2 158 Virtuoso Reference Manual Copyright 1996 Eonic Systems Debugging environment under Virtuoso EM2
257. e additional register swappings required for C tasks The nanokernel is not aware of the manipulations performed by the micro kernel As far as it concerned there is only one PRLO process which it exe Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI2 7 Virtuoso on the ADSP 2106x SHARC 21 7 2 cutes whenever no PRHlI process is ready to continue This makes it possible to use the nanokernel on its own Internal data structures The user does not normally need to access the internal data structures used by the nanokernel The documentation in this section is provided only for a better understanding of how the nanokernel operates A process is represented by a pointer to a Process Control Structure PCS For PRHI processes the PCS occupies the first eight words of its stack Two entries are placed at the top because of the decrementing stackpointer A static PCS is used for the Idle process More details on the PCS will be intro duced in the section on process management A channel is represented by a pointer to a Channel Data Structure CDS The first word of a CDS is a pointer to the PCS of a process waiting for that channel or NULL Other fields depend on the type of the channel and will be introduced in the section on nanokernel communications The following static variables are used by the nanokernel to keep track of the state of the system NANOK_PRHI Pointer to the PCS of the current PRHI process
258. e cable should be wired as shown below EVM TARGET R Data X Data R Sync X Sync X Data gt R Data X Sync R Sync R Clock lt X CLock out X Clock not connected R Clock in TIt 6 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Texas Instruments TMS320C30 amp C31 To use this host interface link with SERH LIB instead of LSIH LIB modify the TEST CMD file and re MAKE The interface program on the EVM should be running before the application is booted on the target board It is not nec essary to reload it each time but a reset will be required You can test the interface using the LSI board and only one PC as follows 1 remake one of the examples as described above 2 Type EVML to boot the EVM Type ERUN TEST to reset the EVM boot the LSI board and restart the EVM server 35 6 Interrupt handlers and device drivers for Virtuoso on the TMS320C3x 35 6 1 Interrupt handling in Virtuoso This section describes how interrupts are handled in Virtuoso It will be of interest to users who need to write their own interrupt handlers and device drivers Interrupt handling is easily the most processor specific part of any piece of software Some of today s processors are able to accept interrupts at fre quencies well into the megahertz range It is virtually impossible for a soft ware kernel to support task swapping at anything approaching t
259. e channel and will crash the system if there isn t PRLO_PUSH is used by the K_taskcall function to send command packets from a task to the microkernel process TI2 40 Virtuoso Binding Manual Copyright 1996 Eonic Systems Alphabetical List of nanokernel entry points 38 17 SETISR1 BRIEF Moves an ISR to level 1 setting the global interrupt enable bit e CLASS Interrupt service management e SYNOPSYS LATcond SETISR1 SETISR1 is defined in TRAPS INC e DESCRIPTION This call increments the level 1 ISR counter and returns with the global inter rupt enable bit set It should be used by ISRs that may take a longer time than allowed by the interrupt latency requirements of the application e ENTRY CONDITIONS ST and R11 are saved on the stack e EXIT CONDITIONS The global interrupt enable bit in ST is set R11 is corrupted all other registers are preserved EXAMPLE This ISR disables the timerO interrupt while processing the IIOF3 interrupt with global interrupts enabled This is an example only it is not normally necessary within Virtuoso to dis able the timer interrupts within an ISR include traps inc def _ iiof3_isr text __iiof3_isr push st push rll pushf rll push aro push arl acknowledge interrupt if necessary lat SETISR1 move to ISR level 1 push ar2 push iie Save current IIE register andn 0001h iie disable timerO
260. e declared in iface h Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 145 System Configuration example DRIVER ROOT HostLinkDma 0 3 PRIO_ALT DRIVER NODE1 RawLinkDma 2 PRIO_DMA DRIVER NODE2 RawLinkDma 5 PRIO_DMA DRIVER NODE1 Timerl_Driver tickunit 14 3 1 Link descriptions Each Virtuoso node is connected with other Virtuoso nodes through links A link is a communication channel composed of a physical carrier between two ports Each port is processor dependent and requires a specific driver to be installed on the port Two types of links are distinguished 1 Netlinks exclusively used by the Virtuoso system and only indirectly by the user upon issuing a kernel service A Virtuoso specific kernel protocol is used The netlink connections are described as pairs of ports owned by the nodes the driver resides on SYSGEN EXE will find all shortest routes from any node to any other and compile the routing tables An error will be reported if the network is not fully con nected 2 Rawlinks exclusively used by the application tasks for direct commu nication with a task on a neighboring processor or an I O device The datatransfer is a raw bit protocol The raw links are only indicated by their driver Note the physical carrier for any type of link can be any type of hardware e g twisted wire cable bus connector
261. e ie ADI 21 Ke TasSkCallllxsie ese e i ein oh ee Bd it a a E aa os SA Se Pe et a ADI 22 KS DisablelSR mia Ae eile ei i N a ADI 23 KS Enablel SB E EEE EEEE E E robe atuetes E ADI 24 PRAHI GET taii hava era aae a r a a weet aiahivas ADI 25 ain E AA E E E E A E A E T ADI 26 PRA ROP a a a A Rhee ADI 27 PRHIPORW nea e ea a ieee Sahai oGees ADI 28 PRAO RU T A r Cac I ta et ADI 29 PRAK RSH eere aieia aea e e eara eaae Eea beL Erne ADI 30 An Ee E E A A E E ADI 31 PRAIEWATI cote sc cose enteeaaae e e a te dante aedads ADI 32 PROGR SE sts fects EE E es tate ak heat er et ae Be Ae Sted ADI 33 YIELD 22 escetie a tient avi r a Catia ADA eet cena ADI 34 Predefined drivers ADI 35 Virtuoso drivers ON the 21060 oi ececceeeeeecceeeeeee ceeeeeeeeaeaeacaeae cesseeeeeeeeaeseaeeeeeess ADI 35 The timer device river erida aaa a ahd EA ee eee ADI 36 The host interface device LIVER ccececceceeesceceseseeeeeeecaeeeeeeeaeeeseeeeeseeess ADI 37 N6tIIAK GriVErS nea rna eRe til ewe a aed Mae etic ADI 37 Raw LINK drivers c ccccececsssssssesceceeeeesceseeseeeceececeeesassuseeeecaeaeaeae eieaa aa atean aia ADI 39 Common remark for all link drivers e cc cecccccececeeeccceeeesceeceseeeeeseseeeesesteeeess ADI 39 Task Level Timings ADI 40 Application development hints ADI 42 Virtuoso on the Intel 80x86 11 1 Notes over PC interrupt drivers ss ensssssnesseernnseesrtrsrtnetnrerrstrrnnttntrnssrnss re
262. e ker nel can detect this as well While most transputer would then simply display all symptoms of classical deadlock the kernel is able to continue to execute all other tasks and eventually reset and reinitiate the communication Device drivers with Virtuoso on the INMOS transputer Although on the transputer every communication acts as an interrupt by acti vating a process the transputer itself does not know the traditional interrupt mechanism Nevertheless all interrupts can be handled be it with a different hardware and software methodology In general you will see that interfacing to peripheral devices can be simpler than on most traditional processors Only remember that the links timers and the event pin must be accessed through the kernel services if Virtuoso is running on the processor The driver itself can be written at the Virtuoso microkernel task level using the kernel provided interfacing routines or the user can write a driver as a high priority process Be aware that the driver is scheduled in FIFO order and must be kept short in order not to monopolize the CPU too long Below we outline various schemes a Use a separate transputer For example the 16 bit T225 to interface to the peripheral device and com T8 8 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the INMOS T2xx T4xx T8xx municate with it through a link This solution is fast and simple It assumes that you will run o
263. e microkernel uses this type to imple ment its free list of command packets data packets and timers If used for data communication it behaves as a LIFO buffer Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 2 11 Virtuoso on the ADSP 2106x SHARC The LIFO_CHAN structure has two fields CH_PROC pointer to the PCS of a waiting process or NULL CH_LIST pointer to the first element of the linked list or NULL The nanokernel services that operate on this type are PRHI_GETW wait action PRHI_ GET test and modify action PRHI_PUT signal action 21 7 7 STACK_CHAN Stack channel This type of channel uses a memory block as a data stack The microkernel uses a stack channel to input commands from tasks and the network drivers and to receive events from interrupt handlers The STACK_CHAN structure has three fields CH_PROC pointer to the PCS of a waiting process or NULL CH_BASE pointer to the base of the stack CH_NEXT pointer to the next free word on the stack The nanokernel services that operate on this type are PRHI_POPW wait action PRHI_ POP test and modify PRHI_PSH signal action 21 7 8 Register conventions In order to understand the register conventions adopted by the Virtuoso nanokernel the following register sets should be introduced CSAVE r3 r5 r6 r7 r9 r10 r11 r13 r14 r15 iO i1 i2 i3 i5 i8 i9 110 111 i14 i115 m0 m1 m2 m3 m8 m9 m10 m11 mrf mrb MODE1 MODE2 USTAT
264. e node prio entry stack groups ae as 5 ky TASK STDIODRV NODE1 3 stdiodrv 256 EXE TASK HELLO NODE1 10 hello 400 EXE queue node depth width SE TNE a na QUEUE STDIQ NODE1 64 4 QUEUE STDOQ NODE1 64 4 P1 42 Virtuoso User Manual Copyright 1996 Eonic Systems Simple Examples al resource node fe RESOURCE HOSTRES NODE1 RESOURCE STDIORES NODE1 The task STDIODRV the queues STDIQ and STDOQ and the resource HOS TRES and STDIORES are used in the run time system to coordinate accesses to the host The only application task defined here is HELLO The body of the application task is as follows include lt _stdio h gt void hello printf hello world n Note that the stdio include file has a leading underscore to differentiate it from the include files that are often provided with compilers so you can be sure that the Virtuoso version of the file is used Then a function called hello is defined The name of the function is the same as the entrypoint specified in the system definition file The use of the stdio function printf is absolutely standard Next modify the makefile The code for the application tasks is compiled into a library controlled by the variable TASKS hello obj Assuming that the above file is called hello c default rules in the makefile will compile and link the code automati
265. e of a non leaf procedure with stack labels This is the same as leaf prologue and epilogue with 2 extra moves to save and restore the SSH Extra prologue instruction movec SSH y R7 N7 Extra epilogue instruction move y R6 SSH 29 5 5 Stack layout Interfacing C and Assembly allows the user to utilize the benefits of both lan guages in programming tasks When interfacing C and Assembly it is essen tial that Assembly language that is called from C must match the compiler s conventions Although not strictly required it is recommended that all assembly language routines used the standard stack usage conventions so that these routines can be called from within C code or vice versa Here is an example of a C program calling an assembly language routine extern int asmsub main Copyright 1996 Eonic Systems Virtuoso Binding Manual M3 13 Virtuoso on the Motorola 96K DSP int i argl arg2 arg3 i asmsub argl arg2 arg3 The assembly language routine is declared as an ordinary external C rou tine According to the compiler s naming conventions the C code will contain a Call to a global symbol named Fasmsub That is the compiler prepends an upper case letter F to each C procedure name Therefore the assembly lan guage must define a global symbol of this name that is XDEF Fasmsub Fasmsub lt entry code prologue gt lt body of routine gt lt exit code epilogue gt
266. e runable The lower priority task is placed into a temporary state of suspension and execution control is granted to the higher priority task Eventually control is returned to the interrupted task and it is resumed at the point of its interruption Thus when any task is given execution control no higher priority task can be in a runable state This is an important point to remember When all application tasks are in an unrunable state control is granted to the null task The null task is a do nothing task which allows the system to run in an idle mode while waiting for an event that will resume or start a higher priority task The null task is always the lowest priority task in the system and is P1 24 Virtuoso User Manual Copyright 1996 Eonic Systems Functional support from Virtuoso always runable the main part of your application program It is a required part of the system and may be customized by the user if special needs exist e g to halt the processor when idling The only condition is that it must never be blocked from running In Virtuoso the null task is also used to mea sure the workload of the local CPU 4 7 2 c Task execution management Virtuoso provides a number of services that directly control the execution state of a task These services can operate asynchronously of the current execution thread of the task A task normally starts its life by a KS_Start call This call can be invoked during start up
267. e saved the interrupted context so that the exit sequence e EXIT CONDITIONS e EXAMPLE listed below would correctly terminate the ISR pop ar2 pop arl pop aro popf r11 pop rll pop st reti This call terminates the ISR and does not return This ISR accepts the IIOFO external interrupt and sends a signal to two hi priority processes include traps inc ref _chanl_ptr ref _chan2_ptr def _ iiof0_isr text __iiofO0O_isr push st push rll pushf rll lat SETISR1 move to ISR level 1 S S S push ar0 pu pu h arl h ar2 Copyright 1996 Eonic Systems Virtuoso Binding Manual TI2 27 Alphabetical List of nanokernel entry points interrupts are enabled from this point j any other useful code lat PRHI_SIG send signal on chanl ldi _chanl_ptr arl nop or other useful instructions nop F xecuted before the PRHI_SIG HB s lat PRHI_SIG send signal on chan2 ldi _chan2_ptr arl nop nop oss lat ENDISR1 terminate the ISR nop nop nop e SEE ALSO SETISR1 e SPECIAL NOTES A normal interrupt exit popping saved registers and RETI is not allowed for an ISR running at level 1 TI2 28 Virtuoso Binding Manual Copyright 1996 Eonic Systems Alphabetical List of nanokernel entry points 38 5 K_taskcall BRIEF Sendacommand packet to the microkernel process e CLASS Process communication e SYNOPSYS void K_taskcal
268. e simultaneous Microkernel services for scheduling and cancel ling timed events are an integral part of the microkernel Most microkernel calls that involve the cooperation of another task or device can be invoked to wait until synchronization is established As this can cause some tasks to be blocked indefinitely it is possible to limit the waiting time to a time interval provided as a parameter of the microkernel service that caused the task to wait This time interval is called a time out and makes use of the microkernel timers When the time out expires the service returns with an error code A cyclic timer ____ _________ A one shot timer FIGURE 5 Types of timers 4 7 4 Class Memory In any system memory is a resource for which tasks are competing Mem ory management is an area where various techniques can be applied Many techniques are very fast and utilize elegant models for allocation and deallo Copyright 1996 Eonic Systems Virtuoso User Manual P1 27 Functional support from Virtuoso cation Unfortunately most have a common flaw one which is very serious in a deterministic environment fragmentation Fragmentation refers to the dis organization which occurs when memory is allocated from and released to a common memory pool At some moment it is possible that a request for a certain block size fails because not enough contiguous memory exists even though the total amount of free memory exceeds
269. e task to another forms the basis of multitasking The result is the appearance of several tasks being executed simultaneously 4 7 2 b Priority and scheduling When several tasks can be competing for the resource of execution time the problem is to determine how to grant it so that each gets access to the sys tem in time to perform its function The solution most often used is to assign a priority to each task indicative of its relative importance to other tasks in the system Virtuoso uses a fixed priority scheme in which up to a user defined maximum number of tasks may be defined Tasks which have a need to respond rapidly to events are assigned high priorities Those that perform non time critical functions are assigned lower priorities Without a kernel most processors only know one priority level The exception is the transputer that uses two priority levels In itself this is not sufficient to solve all hard real time applications but it has proven to be helpful when designing Virtuoso for the transputer Virtuoso provides an efficient software based way of assigning multiple priorities to tasks It is the priority of each task that determines when it is to run in the hierarchy of tasks When a task may run depends on what is happening to the tasks of higher priority Tasks are granted execution time in a strict descending order of priority While executing a task may be interrupted by an event which causes a task of higher priority to b
270. e two tasks Even more a semaphore will not assure perfect synchronization as a sema phore is counting Hence a task could signal more than once while the syn chronizing task has not even started up When using queues to transfer data one obtains this effect as long as the queue is not full On the other hand a message transfer will assure perfect synchronization as the sending as well as the receiver task synchronize at the same time On using the single processor versions for multiple processors If you only need a few processors and if you need to minimize on memory usage at all cost it might be advisable to use the multi processor version of Virtuoso MP implementations The difference is that the VSP distributed version of the kernel has an embedded router enabling to keep the original Virtuoso source code programs while you only will need to reallocate the dif ferent tasks queues semaphores etc So simply by adding processors and by invoking the configurer of the compiler the system will run faster without changing any of the source code provided you used separate compilation in the first phase Of course this kernel uses more memory In order to use the single processor version on multiple processor you will develop the program running on each processor as usual and configure the system using the configurer from the compiler This time however you will need to use the kernel services KS_LinkinW and KS_LinkoutW or equ
271. e workload period to 300 ms KS_SetWlper 300 KS_Workload The workload monitor section in the debugging chapter of this manual The actual range of the period is processor dependent as each processor has a different granularity for its timer P2 94 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services 11 57 e SUMMARY e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO KS _ Signal Signal a semaphore Semaphore void KS_Signal K_SEMA sema The KS_Signal microkernel service is used to signal a semaphore If the semaphore waiting list is empty the semaphore counter is incremented oth erwise the first highest priority waiting task is rescheduled NONE K_SEMA SWITCH KS_Signal SWITCH signal semaphore SWITCH KS_SignalM KS _ResetSemaM KS_ Test KS_Test M W T Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 95 Alphabetical List of Virtuoso microkernel services 11 58 KS SignalM e SUMMARY Signal a list of semaphores CLASS Semaphore e SYNOPSIS void KS_SignalM K_SEMA semalist e DESCRIPTION The KS_SignalM microkernel service is equivalent to but much faster than calling KS_ Signal for every semaphore in the list The signaling of the sema phores is atomic if this service is used instead of multiple KS_ Signal calls A s
272. eafter we will give a reference type overview of the microkernel classes and their functions Finally a complete example on how to use the interface is given 17 2 Kernel object generation by sysgen Sysgen normally generates a number of C andheader files to define kernel object ID s and data structures Using command line switches it becomes Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 177 Microkernel C interface possible to have sysgen generate C header and implementations files that declare and define the C kernel objects In order to generate the C files the user must pass the flag oCH to sys gen The usual C files and header files are still needed to make a valid appli cation so one should always use ochCH as command line flags to generate all necessary files When given the C and H parameters to the o flag sysgen will generate the following files m vkobjcts hpp this file contains the declarations for the kernel objects that are visible to all nodes of the target This are all objects defined in the sysdef file with the exception of the memory map objects m vkobjcts cpp this file defines and initializes the objects declared in vkobjcts hpp The correct parameters are passed to the constructors of the objects m vkobnunn hpp this file declares the objects that are local to node nnnn This is restricted to the memory maps objects m vkobnunn cpp this file defines and initializes the obj
273. eatotekee ADI 1 ADSP 21020 addressing modes 00 2 cccceescecceeeeceeeeeeceeeeeeeaeeeaaaaeeeseaeaaeeeeeaeaaeeenaes ADI 4 Special purpose registers on the ADSP 21020 000 eecceeeeeceeeeeeeeee tees eaeeeenaeaeeeeaes ADI 5 MODE 1 register and MODE2 register cceeeceeeeeeeeeeeceeeeeeceeeeaeeeeeenaees ADI 5 Arithmetic status register ASTAL ics ype tal dite ADI 6 Sticky arithmetic status register STKY 0 cecceeeeeeeeeeeeeeeceeeeneeaeeeeeeeeeeesaees ADI 7 Interrupt latch IRPTL and Interrupt Mask IMASK eeeeeeeeteeeeeeeeeees ADI 8 Program memory Data memory interface control registers c ee ADI 9 PC stack PCSTK and PC stack pointer PCSTKP ecseeeseeteeeeeeeteees ADI 9 Stat s SLACK sete toe tte dte neuian eie e EREA E ea RANAS Ea EEE A ER ADI 9 USTAT rerien eraan ea E aE cereale AE RE E E EEE RET STARE ADI 10 Relevant documentation ec cece tor yeatieciss say aes ate snatse eee Se dieded eves dddeeudeaindde Seeneee ADI 10 Version of the compiler oiocesisseeanatcsarsekelbceaceneeibaue deen teelicne eat ruteren erenneren renerne ADI 10 R ntime Enyin meN seiate en eea yaeta R ae ENa ADI 10 DEIRI EEEE E A Ae tae Ret ee ae tae ADI 10 The Arehitecturefile x cee stank cet a latest ord a a a Rte weed ei ADI 11 Runtime header interrupt table ceeecesceecee cee eeeeeee eeeeeeeeeeeeeeeeeeeeeees ADI 12 Assembly language interface sxSicie Sie sateassv sec 2eyateieda
274. ecececececeeceneeceeaeceaueeeeseeesaueaueeeesaaeeanneseneress P2 125 Host interface low level driver eeccecceeesceeceeesseeeceeeseeeeceeeeeeee seeaeeeeeeesaeeeeeeeaes P2 125 Higher level drivers sroine ana iaa dicey aan ai aeaea echo ee KETA ainda ead P2 126 Console input and output isceiccctasteediteveecstecssieeeccendtiweceaetedekedaer one P2 127 Standard O GIVER ecsczecidece ois chees ceadadeeteiedcsessesteereets iiaee tantei iiaa P2 127 Graphics driver 2 Sree a IN es See ol eiaan ce aa cake eee rennet P2 127 Runtime libraries P2 128 Standard VO t nctionS yesi imele ase aed cad e Taa a P2 128 Implementation limits coscscen iin iia see eieanaeeen elle P2 128 Standard WO functions coc ses ecteett en ccedbetsabesee tuned eteedetedean ventas graves ents cuesseatetees P2 128 POiQraprniics WO eeraa aai nt Beaty ete aao A aR A E A P2 131 OVErVI W terasi ni e T E a E E TAT P2 131 Driver and mode selection cece ceeeeeeeeeeeeeenee ceeeseneeeceeeeneee eeeeeeeeeeeee P2 132 Read or write graphics parameters and context seseeeeeeceeeee neers P2 134 Drawing pixels and lines sj sae sve kane eee dele os Siete vealed oe eae P2 136 Drawing fill g TOMS sats hased a a ng esi a a et aa et P2 138 TEX Plotin kiera a oa e vores a a a a EA P2 139 Other graphical calls isser a E E aE P2 139 System Configuration P2 141 System configuration COncepts eeeeceeeeseeceeeesseeceeeeeeeeceeeeeeeeeeeeea
275. ecial Notes Copyright 1996 Eonic Systems Virtuoso Binding Manual M3 23 Virtuoso on the Motorola 96K DSP 29 13 29 14 29 15 Developing ISR routines When developing Interrupt Service Routines the ISR conventions described in paragraph 29 6 1 have to be followed The best place to install and enable an ISR is in procedure main where predefined drivers like the driver for the timer interrupt are installed and enabled It is possible that additional initialization of registers and or peripheral I O has to be done The best way to do this is writing a C callable procedure that does the necessary additional initializations and call this procedure after the call to KS_EnableISR An example of this method is the installa tion of the timer ISR in procedure main include iface h extern void timerO_irgh void extern void timerO_init void int main void KS_EnableISR 4 timerO_irgh IPLEVEL2 IPMNEDGE timerO_init The nanokernel on the 96002 Section in preparation Predefined drivers Two devices drivers are already added to this release of the Virtuoso kernel They are m the timer device driver a the host interface device driver The timer device driver is needed for time out features of some kernel ser vices and for kernel timer services The host interface device driver is written to be able to communicate
276. ect Priority A rendezvous point for microkernel message passing to synchronize sending and receiving tasks No data is stored or buffered in the mail box A class of microkernel service In addition to the standard system heap real time memory allo cation of fixed size blocks is provided Information used with a mailbox Consists of the header structure and the data to be communi cated High level API for real time programming Also refers to the system provided process that implements microkernel services Copy memory from any address on one proces sor to any address on another processor with out synchronizing with any other task Multi processor A product version that provides the full range of services within one processor plus raw link drivers to communicate with other processors Also appropriate for single proces sor systems where the links may be used to communicate with peripherals An multi tasking API between the microkernel and interrupt handlers providing simplified functionality for lower overheads Processor containing a single CPU with asso ciated memory and peripherals Each node runs a separate instance of the kernel A structure on which microkernel services act Objects are declared in the system definition file The integer value that controls the order of scheduling of microkernel tasks A smaller value indicates a higher priority and the valid range is 1 to 64 GLO 2 Virtuos
277. ects declared in vkobunnn hpp The correct parameters are passed to the constructors of the objects The objects defined in the files written by the sysgen correspond to objects defined in the sysdef file The only exception is the object representing the active task The name of the object representing the currently active task is ActiveTask The names of the other C objects are related to the name ID s given in this sysdef file The cpp files where these objects are defined and initialized makes the rela tionship between the object names and the name ID s very explicit The argument to the constructor for a global kernel object is indeed the name ID of the object If the user wants to control the naming of the C objects he must understand the mechanism that maps an ID name to a C object name The C object name is constructed from the sysdef name ID using the fol lowing scenario 1 If the first three or more characters of the ID name are identical to the first characters of the object class name without the leading K of course then these characters will be replaced by the class name The remainder of the ID name will be converted to lowercase except for the first character which is forced to uppercase Examples QUEUE becomes Queue1 The ID MAILBRESULT of a mailbox object is seen as MAILB RESULT As the first five characters match the first five charac ters of mailbox sysgen will generate the name MailboxResult for
278. ed one per word or where sizeof does not return the number of 8 bit bytes in a type P2 60 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services 11 30 e SUMMARY e CLASS Saw es e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE KS _Linkout Start to write a datablock to a link and continue Processor specific int KS_Linkout int link int size void datablock This call writes data to a processor link It is possible to wait on the termina tion of this event at a later stage in the program Event number int LinkEventl LinkEvent2 int Block1 200 int Block2 200 start output operations inkEventl KS_Linkout 1 200 Blockl inkEvent2 KS_Linkout 2 200 Block2 other code not using blocks z wait until link operation finishes z KS_EventW LinkEvent1 KS_EventW LinkEvent2 data in blocks can be overwritten Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 61 Alphabetical List of Virtuoso microkernel services SEEALSO KS_LinkoutW KS_LinkoutWT KS_LinkinW KS_LinkinWT iface h e SPECIAL NOTES Attempting to write to a link without using this service may cause unpredict able side effects on some processors The size parameter is the number of 8 bit bytes to be written Care needs to be taken when spec
279. eeceeeeeeeceeeeeeeeeeeeeeeeeeeeeeenee tees P2 17 Memory management microkernel services eccceeeseeeceeeeeeeeeeeeeeaeeeeetee resne P2 18 Special microkernel services cc ceeceeeecceeeeeeee ceeeeeseeeeeeeeeeeeceeeeeaeeeeeeaaeeeeeeenaeeeenens P2 18 Drivers and processor specific Services 00 0 e ceceeececeeeeeeee ce eeeeees eeeeeeteeteaeeeee tees P2 18 Nanokernel types and datastructures P2 21 Nanokernel processes and channels ccccseeceeeeceeeeeceeeeeeeeceeeeeeeeeeeeeeeeenees P2 21 Nanokernel channels iscri Sek rea tetas Gree eects eei aeaa auau nin Recents P2 21 Nanokernel services P2 23 Process management 52 5 Stcecsiceiecttsaettedcans lease ee tendeneubalitsteatdeanent clepaagdeeetese P2 23 ISR ma gement seeriaid ienser arka ed Ee se e aden eai SAE AASE AREE ENER SRA P2 24 Semaphore based services ov cs c2cc2sccchenenSeveensbte aadeses ecdeesabes teesdeeed seadscedeeeeeunteenebes P2 24 Stack DASE SerViICES sorser k a a dts a aa a a vet set T ber eee P2 24 Linked list based services c2acc aekateead ca2eae ac cangenneteamanseeceaanchceersechentumaedaheetuedine P2 24 Copyright 1996 Eonic Systems Virtuoso User Manual TOC 3 Alphabetical List of Virtuoso microkernel services P2 25 KS DADO sess hs elect eis oe ae as cei ea eet ees at tte eet a te P2 26 KS ADOG A iceciicen Sabie tee ier Acne eve vests leash Shee abt dae esha VA caeanee tee P2 27 KS sADOME ME SEE E EE E ee as EAA a
280. eeeeneeene P2 177 Klask ereenn a a a cede tate tnen urea ceeds Donate Sesh E rete P2 179 ACTIVE TASK EE EE E SE E E EEEE ttouaa de cag A nnaaniaadecmne P2 180 FFAS KG OUND opie teat t e te Mee a ate Mata A etc Gia Rett ead E P2 180 POSSI AD MOG eee tine ite ae ete tacit cia semecene E ed cole ateeediens P2 181 PSN FEO HE ssa tat att cee ar stn an eae eat a ot mal P2 182 KES AG cas fee ag caiccdetiaee Seta E E ec a chee tee daaaue wench ie dues eda aouetacuret P2 183 KO UE a instants deecsansiuns a a a a a tees avuns cx EEEa AA TERS Naaa ta P2 184 KMemory Map veii anana a ek te eee E A A ET P2 185 KRESOUIGCE e a ia pe a E e E T a P2 186 KITIME eodera eean eeo eae eiei Oana naat E Adee aa E Aae A OSE EASE EEE aes ERASER P2 187 A sample C application osneessenneeonneseeeeneeerorrtestertnretrnste renterne trneeenss reren nere ree P2 188 Sysgen generated files aetecses seaievee wes SWaid eeetenlarddeaubne ae P2 189 Changes to the program files cceeceeceeescceeeeeeeceeeeeeaeeeesaeaeeeeeeeaaeeeeaaeaes P2 191 ERADS and Pittall S Of CEP inica Scns tend rie becuse reo ante e eE P2 197 Copyright 1996 Eonic Systems Virtuoso User Manual TOC 7 Part 3 Binding Manual P3 1 Virtuoso on the Analog Devices 21020 DSP ADI 1 Virtuoso implementations on the 21020 ooo eee seeeee tent eect eee eeeeeeeeeeeeeeeeaaeeeenea ADI 1 DSP 21020 chip architecture icsregerisdceceavee tober eeasintetsioctet prastcdiennlni
281. eference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services dictable side effects on some processors The size parameter is the number of 8 bit bytes to be read Care needs to be taken when specifying the size parameter on systems where characters are stored one per word or where sizeof does not return the number of 8 bit bytes in a type Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 57 Alphabetical List of Virtuoso microkernel services 11 28 e SUMMARY e CLASS ene ee e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES KS_LinkinW Read a datablock from a link with wait Processor specific void KS_LinkinW int link int size void datablock This call reads data from a processor link The call returns when the dat ablock has been read in Meanwhile the calling task is put in a LinkWait State NONE char buf 128 read 15 bytes from link 3 store it in buf EZ KS_LinkinW 3 15 buf KS Linkin KS_LinkinWT KS _Linkout KS _linkoutW KS_LinkoutWT iface h Attempting to read from a link without using this service may cause unpre dictable side effects on some processors The size parameter is the number of 8 bit bytes to be read Care needs to be taken when specifying the size parameter on systems where characters are stored one per word or where sizeof does not retur
282. efiles supplied in the EXAMPLES directory can easily be modified for your application They also show how to organize things so you can optionally include the task level debugger CMD FILES copy from the examples and modify as necessary In the examples LSIC30 CMD defines the memory layout and section placement and TEST CMD contains linker commands and object filenames YOUR SOURCE FILES in the examples this is just test c The pc host program Type LSIHOST lt ENTERP gt to obtain a help screen The default port address can be changed if you recompile the host program The server requires Borland BGI screen drivers if the graphics output func tions are used The EGA VGA driver is required to run some of the example programs and is supplied on this disk s A path to the directory holding the BGI files should be defined as an environment variable BGIPATH e g SET BGIPATH C VIRTUOSO C30 5 Recompiling the PC programs All PC executables have been developed using BORLAND C and TASM but they should be quite portable 6 Using the serial links as a host interface It is possible to use the TI EVM board to connect a stand alone C30 board to the PC A simple program running on the EVM passes the host protocol packets from the target board to the EVMHOST running on the PC and back Serial port 0 on the target board should be connected to serial port 1 on the EVM The clock for the serial link is generated on the target board Th
283. efinition file is used In this file following a simple syntax the user should describe his application in terms of topology and kernel objects with their attributes When done Sys gen is invoked to parse the system definition file and to generate all neces sary include files 14 1 1 Kernel objects The concept of the Virtuoso kernel is those of objects that are used by the programmer to achieve the desired result Each object is of a predefined type and the application task can invoke the kernel services to operate on these objects During the system definition phase the user must supply the names and attributes of each object This will automatically create the kernel objects as datatypes in C syntax in the include files The predefined kernel objects are listed and explained below The names of the kernel object relate with the predefined kernel datatypes NODE Virtuoso network node where an instance of the kernel is run ning NETLINK defines a communication channel between two nodes DRIVER defines a driver function TASK keyword for a Virtuoso task RES keyword for a Virtuoso resource MAP keyword for a Virtuoso memory map MAILBOX keyword for a Virtuoso message mailbox QUEUE keyword for a Virtuoso message queue SEMA keyword for a Virtuoso semaphore Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 141 System Configuration 14 2 Note that the K_TICKS are defined in the mainx c file by the user Sy
284. egisters a PMWAIT 14 bit register that controls the wait states and the wait mode of the program memory banks Bits 12 10 set also the program memory page size a DMWAIT 24 bit register that controls the wait states and the wait mode of the data memory banks Bits 22 20 set also the data memory page size m PMBANKx defines the begin of the program memory banks DMBANK x defines the begin of the data memory banks 18 4 6 PC stack PCSTK and PC stack pointer PCSTKP The 21020 ADSP is provided with two registers that control the stack man agment PCSTK top of PC stack 24 bits wide and 20 deep PCSTKP PC stack pointer 5 bits PC stack holds return addresses for subroutines and interrupt services and top of loop addresses for loops The PC stack is popped during return from interrupts RTI return from subroutine RTS and termination of loops When the PC stack is full the full flag is set in the STKY register so that an interrupt can be generated The PCSTKP is a 5 bit readable and writeable register that contains the address of the top of the PC stack Note This PC stack is not very useful in a multitasking environment If instructions that invoke the PC stack are used one has to save that PC stack when a task is swapped out see further 18 4 7 Status Stack The status stack is five levels deep and is used for interrupt servicing The ADSP 21020 automatically saves and restores the status and mo
285. ek P2 130 fsetpos P2 129 fstat P2 130 ftell P2 130 Functional support P1 18 fwrite P2 129 G getallpalette P2 134 getarccoords P2 140 getcurrcoords P2 136 getfillstyle P2 135 getimage P2 139 getmodepars P2 134 getpixel P2 136 gets P2 129 getuserpars P2 135 getviewport P2 134 Glossary GLO 1 graphdefaults P2 133 graphresult P2 134 Group GLO 1 H hard real time P1 20 High Precision Timer GLO 1 Host server P2 121 Host server low level functions P2 125 Implementation limits stdio P2 128 init_process C40 ADI 31 ADI 20 TI2 23 initgraph P2 132 installation P1 3 Installing an ISR routine ADI 15 ADI 5 installuserfont P2 139 Interrupt handling C40 TI2 15 Interrupt latch IRPTL and Interrupt Mask IMASK ADI 8 ISR levels P1 35 ISRO level P1 13 ISR1 level P1 14 K Kernel libraries P1 4 Kernel objects P2 141 kernel objects P1 23 KS_ Abort P2 26 KS_ Aborted P2 28 KS_AbortG P2 27 KS_Alloc P2 29 KS_AllocTimer P2 32 KS_AllocW P2 30 KS_AllocWT P2 31 KS_Dealloc P2 33 KS_DeallocTimer P2 34 KS_Dequeue P2 35 KS_DequeueW P2 36 KS_DequeueWT P2 37 KS_DisablelSR P2 39 KS_DisablelSR C40 ADI 36 ADI 23 TI2 30 KS_Elapse P2 40 KS_EnablelSR P2 41 KS_EnablelSR C40 ADI 37 ADI 24 TI2 31 IX 2 Copyright 1996 Eonic Systems KS_Enqueue P2 42 KS_EnqueueW P2 44 KS_EnqueueWT P2
286. el TIMINGS scsccctcta te dslte Wi caitarie ine 2nava tg tea a a aA e AEAN d Taia ADI 50 Application development hints ceeecceee cece esse eeeeeeeeee ceneeeeneaaneeeeeeeeeneenenaees ADI 51 Virtuoso on the ADSP 2106x SHARC ADI 1 Virtuoso implementations on the 21060 ec ecceececeseeseeeeeeeeeeeeeeeeeeeeaeeeeeeeeeeees ADI 1 SHARC chip architecture c 32225cc ascSeceeana cece ceeata ceases a 0sevecedy decesawaacea nce aaenteeanceoneteueass ADI 1 Relevant documentation cee ceceee ce ceeceneeceeeeeee eeeeeeeee easeee anes daneeeeae nannte aneren mnene ADI 1 Version of the compiler ssa saat salar ets uearGte des suet pemteslec cusp te cna eatiGreatneieetse een ADI 1 SHARC silicon revisions s xsafuia xiv Basse Resulare Ge natal eadd gee dea bade tohnanrsobaclbeteanchewcias ADI 1 Developing ISR routines on the SHARC ceccceeeeeeeeeeeeeeeeeeeeseeeeeeeeeeeaaeeeeenaees ADI 3 G neral PrinCl Plas chee s cen ctaict caine a phot acehd aati e n ADI 3 Writing an ISR routine si leri peinar descr duende mae Bernese ADI 4 Installing an ISR routine scsi soit thecexl aera eat eetitherheeeaMieesedeteadtanien ADI 5 List of ISR related SGniCeS s ccc iced cecdstisldentgueed oeteeienivevarigneardinderisl eres ADI 6 The nanokernel On the 21060 o cece ceesecceceenseceee ceaeeeceeeaaeaeeeeeaeaeeeeeeseeeeeeeesaeess ADI 7 Introduction ct fides teceen tee ET aa O a e S EE aap ER aT ADI 7 Interna
287. emaphore list is an array of semaphores terminated by the predefined con stant ENDLIST e RETURN VALUE NONE EXAMPLE K_SEMA Alarms ALARMI ALARM2 PANIC ENDLIST KS_SignalM Alarms SEEALSO KS_Signal KS_ResetSemaM KS Test KS_Test M W T P2 96 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services 11 59 e SUMMARY e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES KS Sleep Deschedule for a number of ticks Task void KS_Sleep K_TICKS ticks The KS_Sleep microkernel service deschedules the calling task itself and reschedules it after the specified number of ticks It allows a task to delay execution for a certain time in a simple way without using timers or sema phores NONE KS_Sleep 100 delay for at least 100 ticks KS_ Suspend A sleep of zero ticks is equivalent to a call to KS_ Yield Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 97 Alphabetical List of Virtuoso microkernel services 11 60 SUMMARY e CLASS ey eas e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES KS Start Start a task Task void KS_Start K_TASK task The KS_ Start task microkernel service is used to start a task from its begin ning The specified tas
288. emory space required for the queue body is the product of the width times the depth QUEUE CONOQ ROOT 4 1 Mailbox definitions MAILBOX lt name gt lt node gt The name of the Mailbox according to the standard name convention This is the network node the mailbox is placed on MAILBOX slave 3 Memory map definitions MAP lt name gt lt blocks gt lt size gt lt node gt This is the network node the memory map is placed on The name of the Memory Partition according to the standard name conven tion The number of blocks in each map The count must be nonzero The mem ory space required for the map is the product of count and size fields The size field defines the size of a memory block in bytes The minimum block size is 4 bytes MAP ADBuffer 6 16 ROOT Note on the size parameters As Virtuoso supports processors that allow byte aligned addressing as well as processors that only allow word aligned addressing there is a potential problem This is due to the fact that the sizeof function always gives the size in as a difference between consecutive addresses Hence on e g aDSP like the 96K a char is represented as a 32bit word with the most left 8bit rep resenting the char from 0 to 255 and this has a size of 1 While this is gen erally not a problem when working with integers it can be a problem when transferring between two different types of processors Copyright 1996 Eonic Systems Virtuoso Re
289. ems Virtuoso on the Analog Devices 21020 DSP 18 10 6 L_CHAN List channel This type of channel maintains a linked list of memory blocks using the first word in each block as a link pointer The microkernel uses this type to imple ment its free list of command packets data packets and timers If used for data communication it behaves as a LIFO buffer The L_CHAN structure has two fields CH_PROC pointer to the PCS of a waiting process or NULL CH_LIST pointer to the first element of the linked list or NULL The nanokernel services that operate on this type are PRHI_GETW wait action PRHI_GET test and modify action PRHI_PUT signal action 18 10 7 S CHAN Stack channel This type of channel uses a memory block as a data stack The microkernel uses a stack channel to input commands from tasks and the network drivers and to receive events from interrupt handlers The S_CHAN structure has three fields CH_PROC pointer to the PCS of a waiting process or NULL CH_BASE pointer to the base of the stack CH_NEXT pointer to the next free word on the stack The nanokernel services that operate on this type are PRHI_POPW wait action PRHI_POP test and modify PRHI_PSH signal action 18 10 8 REGISTER CONVENTIONS In order to understand the register conventions adopted by the Virtuoso nanokernel the following register sets should be introduced Csave
290. ender field will receive the message If no receiver is waiting on a matching message the call returns an error code and no mailbox insertion is made RC_OK if successful RC_FAIL if not successful K_MSG msg K_TASK RECEIVER char datastring testdata msg size strlen datastring 1 msg tx_data datastring msg rx_task RECEIVER if KS_Send BOX1 2 amp msg RC_OK printf MSG Send OK receiver was waiting n KS SendW KS SendW KS _ Receive KS _ ReceiveW KS ReceiveWT KS_ReceiveData P2 86 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services e SPECIAL NOTES The size member is the number of 8 bit bytes in the message Care needs to be taken when specifying sizes on systems where characters are stored one per word or where sizeof does not return the number of 8 bit bytes in a type Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 87 Alphabetical List of Virtuoso microkernel services 11 51 e SUMMARY e CLASS es es ee e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES KS SendW Send a message and wait for receiver Mailbox int KS_SendW K_MBOX mbox K_PRIO prio K_MSG msg The send message and wait microkernel service is similar to the send mes sage microkernel described above except that the se
291. ending stack i e a push operation pre increments the stack pointer ST Status Register DIE DMA Coprocessor Interrupt Enable Register IIE Internal Interrupt Enable Register IIF IOF Flag Register Copyright 1996 Eonic Systems Virtuoso Binding Manual TI2 3 Virtuoso on the Texas Instruments TMS320C40 36 1 3 36 1 4 RS Repeat Address Register RE Repeat End Address Register RC Repeat Counter Above 3 registers are used by the hardware looping instructions RPTS and RPTB PC Program Counter IVTP Interrupt Vector Table Pointer TVTP Trap Vector Table Pointer Addressing Modes The TMS320C40 has a rich set of addressing modes The major classes are Register Direct using the DP register Indirect with many variations Circular Bit reversed Immediate PC relative Most data processing instructions fall into one of three categories 2 operands one of these is always a register 3 operands two of these are always a register Parallel Relevant documentation It is highly recommended to read carefully the following documentation avail able from Texas Instruments In this manual we only outline the main points TMS320C4x User s Guide Texas Instruments 1992 Edition TMS320 Floating Point DSP Assembly Language Tools Texas Instruments 1991 TMS320 Floating Point DSP Optimizing C Compiler Texas Instruments 1991 TI2 4 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Texas Instru
292. enencmel ese oes P2 154 Entry into the debugger 2c tecdi ea cies cad le lise Oe ddan Si eine cs aah P2 154 Invoking the debugger from the keyboard cccecceeeeeeeeeeeeeeeeeeeeeeneaeeee P2 154 Invoking the debugger from within your program ccceeeeeeeeeteteeeeeaee P2 155 Differences at system generation time ccececceeeeeeeeeeeeceeeeeeeseeeeeeeeaes P2 155 Debugger COMMAS oz gecscnccncrmests sae cunes vesd tect aleceedieen tad debepteepngeatieds deeetusoussens P2 156 Tasks sg seco tegen dato a A EE larly tee RaDa EKANA ARAE AAE da eee P2 156 QUEUES noia a ciated ceed ca aires et neue beer ches dubia T oct P2 158 TOC 6 Virtuoso User Manual Copyright 1996 Eonic Systems DE NMAINONOS Bei ce aed E ta Ree ed das al dae aaa P2 158 FROSOUPCOS oiir aeua aa aa Aeh S aa Aa a ANA A KANEA TEATA EE ala ditemaeeses P2 159 Memofy Partition S aniei hates ae E EE AE TES P2 159 Tracing MORON ariere inidan aea AA KE aa aAA EEKE ETA Ea Es P2 160 Mallok E Sss aeter eae T e E nE dace audeadeadeeve chandeedeadanaeteneess P2 164 Network Butlers esciti iieii aa aaaea EE E EEA Ea a ERA Eei P2 164 Clock ISIS ices sett ttre a n a a A E P2 164 LACK TMT NS EAE A A E T P2 165 Zero Queue Map Resource Statistics ee ceeeceeeee eonna eener reeres rererere P2 165 INGE BOGESSOR c o 2 E E EEE E E A P2 166 Task MAanaQen orane n a a aa Mirae aai aee ied ates P2 166 US DOING asc enctice te tence att
293. ense Agreement 4 4 Distribute on any medium the EXECUTABLE CODE derived from the Licensed Product so long as the Licensed Product is an integral and indistin guishable part of the EXECUTABLE CODE and the applicable runtime license fee has been paid to Eonic Systems 4 5 Extend this Agreement to include more than one SITE by paying the appropriate license fee for the Licensed Product for each additional SITE 4 6 Extend this Agreement to include more than one development station by paying an additional license fee for the Licensed Product for each additional development station 5 CUSTOMER OBLIGATIONS Regarding the Licensed Product the Customer shall 5 1 Include and shall not alter the Copyright or any other proprietary notices on any form of the Licensed Product The existence of any such copyright LIC 2 Virtuoso User Manual Copyright 1996 Eonic Systems License agreement notice shall not be construed as an admission or presumption of publication of the Licensed Product 5 2 Maintain appropriate records of the number and location of all copies that it may make of the Licensed Product and shall make these records available to Eonic Systems upon reasonable request thereof 5 3 Upon termination of this license render written certification that all cop ies of the Licensed Product and any related materials in any form excluding EXECUTABLE CODE have been destroyed 5 4 Take appropriate action by agreement or otherwi
294. er B registers and L registers are only used for circular buffers B holds the starting address while L contains the length of the circular buffer The appli cation developper can also use the alternate registers provided for each DAG This facilitates context switching Again more information about that issue can be found in the Analog Devices User s Manual The ADSP 21020 has a programmable interval timer that can generate peri odic interrupts Three registers control the timer period PERIOD contains the timer period 32 bit register TCOUNT the counter register 32 bit register a MODE2 contains the timer enable bit bit 5 When the timer is enabled TCOUNT is decremented each clock cycle An interrupt is generated when TCOUNT reaches zero Next TCOUNT is reloaded with the value of TPERIOD The instruction cache is a 2 way cache for 32 instructions The operation of the cache is transparant to the user The processor caches only instructions that conflict with program memory data accesses The cache is controlled by two bits in the MODE2 register CADIS bit 4 Cache disable bit a CAFRZ bit 19 Cache freeze bit An IEEE JTAG boundary scan serial port provides both system test and on chip emulation capabilities 18 3 ADSP 21020 addressing modes As already explained in the previous chapter the 21020 processor has two ADI 4 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the An
295. eral steps 1 The arguments to the function must be passed 2 The return address must be loaded into register i13 3 The frame pointer must be adjusted The current function s frame pointer 16 is written into R2 and the current stack pointer i7 is writ ten into i6 to create the called function s frame pointer 4 When the function returns it s necessary to adjust the stack pointer 5 In order for C functions to link with assembly functions use the global and extern assembly language directives The name has to start with an underscore in assembly There is also a possibility to use in line assembly into your C code This is done using the asm construct Example asm bit set model IRPTEN enables interrupts To conclude an example of a C callable function is given int add int a int b segment pm seg_pmco global _add adad dm i7 5 r2 stores old frame pointer dm 1 i6 i13 stores return address dm 2 16 r4 dm 3 i6 r8 dm 4 i6 r0 r4 r4 r8 r0 r4 jump m14 i13 DB delayed jump to return address i 6s i6 dm 0 i6 adjusts stack Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 13 Virtuoso on the Analog Devices 21020 DSP endseg PCSTACK i7 stack pointer A ro r8 r4 i13 i6 frame pointer R2 Bes FIGURE 14 Stack usage ADI 14 Virtuoso Bind
296. erface driver is installed by calling procedure init_server In the examples that accompany the release of the Virtuoso kernel the installation of the host interface is done in procedure main The host interface driver can be used on two levels The lowest level needs only one kernel resource HOSTRES which secures the use of the low level host interface This kernel resource must always be locked by the task that wants to make use of the host interface and unlocked if this task has fin ished using the host interface A list of low level procedures are at the dis posal of the application programmer to do simple character oriented I O server_putch server_pollkey server_terminate server_pollesc Copyright 1996 Eonic Systems Virtuoso Binding Manual M3 25 Virtuoso on the Motorola 96K DSP 29 16 These procedures will do the locking and unlocking of HOSTRES so that HOSTRES is transparent to the application programmer using the low level host interface Also installed in the examples is an easy to use character oriented I O inter face based on two tasks conidrv and conodrv two queues CONIQ and CONOQ two resources HOSTRES and CONRES and a procedure called print1 This higher level interface driver makes use of the low level inter face procedures It is possible to use an even lower level of the host interface Doing this the application programmer can build other host interfaces that do more than
297. erformance cost function in practice one must distinguish the different aspects of the two fac tors Performance and cost mean different things depending on the real application at hand and depending on the particular phase of the product life cycle As such a safety critical system has very different design criteria than a parallel supercomputer although the same components might be used In essence to really estimate the performance cost function one should inte grate over the whole life cycle of the application The latter is broader than simply the product life cycle because current technology is evolving so fast that even during development it might make sense to change the technology in use The reason being that designing the application might take longer than it takes the silicon industry to generate a new generation of processors Therefore in general the statement is that the goal must be to maximize the use of the resources getting best performance out of the used material for a minimum life cycle cost development maintenance and upgrade costs of the application The emphasis is on the application and not on a particular system A system today might use processing components that can change over the life cycle of the application In the light of above when designing an application today we are faced with two major challenges Firstly the very rapid change of technology Secondly while processors are becoming components
298. erneerrnsersrenernnrersene ADI 26 Virtuoso drivers on the 21020 sssesssessssssisesrrssrerrrrritteritrrrtesrreerrinesr nsere ADI 28 Alphabetical List of nanokernel entry points ADI 30 DEVIL 11e 1e EE E E E E E E ADI 31 Stall proCeSs i aha een ils nti india E ADI 32 ENDISRI doricreestwhatdeti to taee ta tecc wesc tec eE o EE E ADI 33 Ke taSKGalll A E etl Gein E AT ADI 35 KS DISABIS ISR eeii eae e a vent alse OiR aE eaaa adii ADI 36 TOC 8 Virtuoso User Manual Copyright 1996 Eonic Systems KS HE Ma DIG SR ake faug neanedes kaye ate hace are nk ete Me Jace ga a ADI 37 PRH GET aaee r e a a ve deadiente teen AE aaia ADI 38 PRHICGETW o ee a E a a ART ADI 39 PRH POPA pi a E E R ADI 40 PRH PROP reee enets esra Ea a eaae ae eaaa EEEE AE a E er ERER ADI 41 PRH PUT oiiire a aaae pE E aE AR EEDE ADI 42 PRH PSH oare teed Sean at ors E a E R Sede ADI 43 BRA Gh E E E E A E ADI 44 PR NN PAI ceire r e e adage amen eos ADI 45 EPS eae ie E Galt a E at aad E eee ata cas ha ada ADI 46 DA naka acs eh Se each GON aed leita Ye ate haar act ell ate ata E ADI 47 Predefined drivers ADI 48 The timer device driver eececeeceee ceeeeceeeeeeeneae eeeeeaeeegeneaeeesenaneeeeanaeneeeeees ADI 48 The host interface device driver g icicvvcionees spcus2etdesh aed welttewedyands teawetiaeole eee ADI 49 Shared memory driver ecceeccececeesceeeeeenseeeeeeeseneesesaaeaesseeeaeeeeeaeeeeeeeneaaes ADI 50 Task bev
299. ers have been assigned as follows 0 31 interrupts enabled in the IIE register 32 35 external interrupts iiof0 iiof3 36 47 used by the raw link drivers 48 55 reserved for Virtuoso internal use 56 63 free Event numbers 0 35 should be used to represent interrupts This conven tion makes the event number the same as the interrupt number used in KS_EnablelSR The remaining numbers are used for events that do not directly correspond to an interrupt For example the dma based raw link drivers install an ISR that accepts a DMA interrupt reads the DMA status and generates the receiver ready and or transmitter ready events The interrupt handlers installed by timerO_driver and timer1_driver gener ate event 48 This is used within the kernel to increment the TICKS time The code fragment below shows how to send an event from an ISR or a PRHI process ref _K_ArgsP def _my_isr _my_isr lat PRHI_PSH send event to microkernel ldi _K_ArgsP arl microkernel input channel ldi EVENT_NUM ar2 event number nop 2 All other values pushed onto the microkernel input channel are interpreted as a pointer to a command packet Command packets are the primary form of communication used within the Virtuoso system They are used by the TI2 18 Virtuoso Binding Manual Copyright 1996 Eonic Systems Programming the nanokernel tasks to request microkernel services sent across the Virtuoso network to
300. ers to their default values void setgraphmode int mode Switches to the selected display mode using the current driver This can only be used if the graphics system is already initialized i e after a Call to initgraph void restorecrtmode void Switches back to the screen mode that was active before the graph ics system was initialized This will normally be a text mode The cur rent driver remains installed and you can return to a graphics display using setgraphmode void closegraph void Closes the current graphics driver To use graphics again a call to init graph must be used void setactivepage int page If the graphics adapter supports multiple pages this call can be used to select the page used by the plotting routines i e the page that is written to void setvisualpage int page If the graphics adapter supports multiple pages this call can be used to select the page used by the video display circuits i e the currently displayed page void graphdefaults void sets all graphics settings to their defaults The next two calls exist mainly for the benefit of the debugger task which has to be able to switch to text mode at any moment If correctly used as described below these calls can be nested and used in application code as well int savescreen void Switches to text mode after having saved the current graphics screen and context in DOS memory This calls returns non
301. erted interrupt instruction words In this case the state of the machine is not saved on the stack A JSR within a fast interrupt routine forms a long interrupt A long interrupt routine terminates with an RTI instruction to restore the PC and SR from the System Stack and return to normal program execution Copyright 1996 Eonic Systems Virtuoso Binding Manual M1 9 Virtuoso on the Motorola 56K DSP 27 4 Relevant documentation 1 DSP56000 DSP56001 Digital Signal Processor User s Manual Motorola Inc 1990 2 G56KCC Morotola DSP56000 DSP56001 Optimizing C compiler User s Manual Motorola Inc 1991 27 5 C calling conventions and use of registers This section contains the following topics Storage Allocation Register Usage Subroutine Linkage Procedure rologue and Epilogue Stack Layout 27 5 1 Storage Allocation The Basic C data types are implemented as follows char 24 bits signed unsigned char 24 bits unsigned short 24 bits signed unsigned short 24 bits unsigned int 24 bits signed unsigned int 24 bits unsigned long 48 bits signed unsigned long 48 bits unsigned float 48 bits double 48 bits pointer address 24 bits max value OxF FFF 27 5 2 Register Usage The compiler register reserves the following machine registers for particular uses M1 10 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Motorola 56K DSP Register Use RO Frame Pointer
302. es DMD bus and PMD bus and the computation units It also provides temporary storage for operands and results The register file consists of 16 primary and 16 alternate registers All registers are 40 bits wide The application develop per can use the alternate register set to facilitate the context switching The alternate registers can be activated by setting two bits bit 7 and bit 10 in MODE1 register Managing the sequence of the program is the job of the program sequencer The program sequencer selects the address of the next instruction It also performs some related functions m incrementing the fetch address m maintaining stacks m evaluating conditions Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 3 Virtuoso on the Analog Devices 21020 DSP decrementing loop counter calculating new addresses maintaining instruction cache handling interrupts More information about the program sequencer architecture can be found in the User s Manual from Analog Devices Inc The ADSP 21020 has also two data address generators DAG1 amp DAG2 The first data address generator produces 32 bit addresses for data mem ory while the second data address generator produces 24 bit addresses for program memory Each DAG contains four types of registers index I mod ify M base B and lenght L registers An register acts as a pointer to memory while the M register controls the step size for advancing the point
303. es no further subroutine calls When the compiler identifies such routines the prologue and epilogue code are opti mized no save and restore of the ssh M1 12 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Motorola 56K DSP For routines which have local variables packed in registers a move instruction will be generated to save the register upon entry and restore it before exiting For all non leaf routines a move must be emitted to save ssh on the stack When local variables exist that couldn t be packed in registers code must be emitted to save and restore the frame pointer and the stack pointer 27 5 5 Stack Layout Interfacing C and Assembly allows the user to utilize the benefits of both lan guages in programming tasks When interfacing C and Assembly it is essen tial that Assembly language that is called from C must match the compiler s conventions Although not strictly required it is recommended that all assembly language routines use the standard stack usage conventions so that these routines can be called from within C code or vice versa Here is an example of a C program calling an assembly language routine extern int asmsub main int i argl arg2 arg3 i asmsub argl arg2 arg3 The assembly language routine is declared as an ordinary external C rou tine According to the compiler s naming conventions the C code will contain a Call to a global symbol named
304. es not return the number of 8 bit bytes in a type Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 77 Alphabetical List of Virtuoso microkernel services 11 43 e SUMMARY e CLASS es es ee e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES KS ReceiveW Receive a message with wait Mailbox int KS_ReceiveW K_MBOX mailbox K_MSG msgstruc The KS_ReceiveW message microkernel service operates like the KS_ Receive microkernel service except that the call only returns when there is a matching message in the mailbox RC_OK K_MSG msg K_MBOX MAILL char data 256 msg size 256 msg tx_task ANYTASK msg rx_data data KS_ReceiveW MAIL1 amp msg printf Received d bytes from d n msg size msg tx_task KS Send KS SendW KS SendWT KS Receive KS_ ReceiveWT KS_ReceiveData Section 7 5 of this manual The size member is the number of 8 bit bytes in the message Care needs to be taken when specifying sizes on systems where characters are stored one per word or where sizeof does not return the number of 8 bit bytes in a type P2 78 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services 11 44 KS ReceiveWT e SUMMARY Receive a message with timed out wait e CLASS Mailbox e SYNOPSIS int KS_ReceiveWT K_MBox mailbox K_MSG msgstruc K
305. ese services are the subject of further development They will be docu mented in a separate application note and in the next release of this man ual Copyright 1996 Eonic Systems Virtuoso Binding Manual Tl2 21 Alphabetical List of nanokernel entry points 38 Alphabetical List of nanokernel entry points e BRIEF scape Sas e CLASS e SYNOPSIS e RETURN VALUE In the pages to follow all Virtuoso nanokernel entry points are listed in alphabetical order Most of these are C40 trap routines some are C callable Brief functional description One of the Virtuoso nanokernel service classes of which it is a member The ANSI C prototype C callable or Assembly language calling sequence Traps The return value if any C callable only e ENTRY CONDITIONS Required conditions before call Traps only e EXIT CONDITIONS e DESCRIPTION EXAMPLE SEEALSO e SPECIAL NOTES Conditions upon return of the call Traps only A description of what the Virtuoso nanokernel service does when invoked and how a desired behavior can be obtained One or more typical Virtuoso nanokernel service uses List of related Virtuoso nanokernel services that could be examined in con junction with the current Virtuoso nanokernel service Specific notes and technical comments TI2 22 Virtuoso Binding Manual Copyright 1996 Eonic Systems Alphabetical List of nanokernel entry points 38 1
306. etails on the use of the host interface see Host server low level functions and Simple terminal oriented I O in the chapter of Runtime libraries The host interface device driver reserves event signal number 8 for its own use 23 1 3 Netlink drivers The NETLINK drivers are used by the kernel to communicate with other SHARCs running Virtuoso Classico VSP Several types are available 1 void NetLink int link_no int buffer _no int direction int speed This is the unidirectional core driver for the link ports It does not use DMA The arguments m link_no buffer_no link buffer you wish to use m direction RX for receive TX for transmit m speed SSPEED for single speed DSPEED for double speed 2 void NetLinkDMA int link_no int buffer_no int direction int speed This is the unidirectional DMA driver for the link ports It can only be used for transfers from or to the internal SHARC memory The arguments Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 2 37 Predefined drivers m link_no buffer_no link buffer you wish to use m direction RX for receive TX for transmit m speed SSPEED for single speed DSPEED for double speed 3 void NetLinkDMAExt int link_no int buffer_no int direction int speed This is the unidirectional DMA driver for the link ports This driver can be used for transfers from or to the internal and external SHARC memory The transfers to exter
307. eturn To wait until execution has finished e g after a change to text mode and before using the console driver use a value returning call such as graphresult This will deschedule the calling task until the result is available The best way to explore the graphics server is to use one of the demonstra tion programs as a starting point and play with it Much practical information can be found in GRINT H The next section gives only a short description of all functions classified by type For detailed information you should consult the documentation supplied with the Borland compiler 13 2 2 Driver and mode selection void detectgraph int driver int mode Tests the graphics hardware and returns the correct driver number for the installed graphics adapter and the highest mode number available from this driver The returned driver value will be zero if the BGI library is unable to use the hardware void initgraph int driver int mode Switches to graphics display using the selected driver and mode The driver parameter should be the value returned by detectgraph or the predefined constant DETECT see GRINT H In the latter case P2 132 Virtuoso Reference Manual Copyright 1996 Eonic Systems Runtime libraries the graphics library will use detectgraph to find out about the hard ware The mode number can be any mode supported by that driver This call clears the display and presets all graphics paramet
308. extremely fast communication and context swapping for a number of processes It also provides the entry points neces sary to integrate interrupt handlers with the rest of the system The prices to pay for speed is that the nanokernel processes and interrupt handlers must obey very strict rules regarding to their use of CPU registers and the way ADI 18 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Analog Devices 21020 DSP they interact with each other From the point of view of the nanokernel an application program consists of a collection of three types code modules m asingle low priority process PRLO process a any number of high priority processes PRHI process m any number of interrupt handlers It is important to understand what exactly is meant by a process A process is a thread of execution that has both an identity and a private workspace These two properties logically equivalent make it possible for a process to be swapped out and wait for an external event while another process is allowed to continue Interrupt handlers in contrast do not have a private workspace The PRHI processes are scheduled in strict FIFO order and must observe the special register conventions mentioned above The PRLO process is assumed to be a C function using the compiler register conventions and must always be ready to execute You can compare it with the Idle process of the microkernel All communicati
309. f obtaining a match between a sender and a receiver message request The sender and the receiver exchange the request in the mailbox Therefore the message operation is actually composed of the two requests and an even tual copy of the data referenced by the message 16 1 3 Using messages The receiving task may want to take different actions depending on the size type or sender of the message It is possible for the receiver to obtain the requested message first and delay the copy until it has decided what to do with the data When the rx_data field in the requested message of the receiver is NULL the kernel will return to the receiving task without perform ing the data copy and the sending task will not be rescheduled The receiver can then base its decision on the size info or tx_task fields of the message which will have been updated by the kernel Finally it issues a KS_ReceiveData call to obtain the data and to reschedule the sending task This is illustrated in the following example This receiver inspects the tx_task field to separate messages from a num ber of senders One of the sending tasks uses the info field to specify an array index Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 171 Practical hints for correct use void Receiver K_MSG M MyType MyArray 100 M tx_task ANYTASK M rx_data NULL M size 999999 larger than any expected message
310. f no block is available within the specified time out the allocation fails but the task is allowed to pro ceed RC_OK or RC_TIME if the call timed out typedef void MyBlock MyBlock p K_MAP MAP1K int RetCode RetCode KS_AllocWT MAP1K amp p 100 if RetCode RC_TIME printf No memory available after 100 ticks n wa KS_Alloc KS_AllocW KS_Dealloc Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 31 Alphabetical List of Virtuoso microkernel services 11 7 SUMMARY e CLASS es es eae e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES KS _ AllocTimer Allocate a timer and returns its address Timer K_TIMER KS_AllocTimer void The KS_AllocateTimer allocates a timer object from the timer pool and returns its address or NULL if no timer is available A pointer to a K_TIMER or NULL K_TIMER MyTimer if MyTimer AllocTimer NULL printf Fatal error no more timers n KS_DeallocTimer KS _StartTimer KS_RestartTimer KS_StopTimer The only legal use of a K_TIMER is as an argument to the microkernel ser vices listed above Programs should not access the structure fields directly P2 32 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services 11 8 e SUMMARY e SYNOPSIS e DESCRIPTION e RETURN
311. ference Manual P2 151 System Configuration 14 11 Other system information and system initialization At the moment of writing some of the necessary system information has to be defined in the mainx c file This mainx c file is the actual program that is executed It starts by initializing the kernel the drivers and the ISR system Some of the global system vari ables and constants are defined here as well These depend on the target processor as well as on the application For example Internal timer clock frequency of 8 333 MHz define CLCKFREQ 8333000 K_TICK period in microseconds Lak define TICKTIME 1000 K_TICK frequency in Hertz define TICKFREQ 1000 K_TICK in CLCKFREQ units Rp define TICKUNIT 8333 number of timers You need at least one timer for each timer that can allocated at the same time plus one timer for each task that may call a WT service at the same tim XJ define NTIMERS 20 number of command amp mail packets Each packet is 52 bytes long 7 define NCPACKS 20 P2 152 Virtuoso Reference Manual Copyright 1996 Eonic Systems System Configuration the size of data packets in BYTES This MUST be the same value on all nodes Ay define DATALEN 1024 data packets are used to buffer raw and message data passing through a node not at the endpoints if you have
312. ficantly longer than the time granularity of your application A special situ ation arises when some tasks are executed at a constant frequency e g when scheduled by a periodic timer In this case it is sometimes possible to observe interference patterns between the task and the workload monitor period As an extreme case consider what will happen if both periods are more or less equal If too short a measuring interval is used the results will be largely determined by the phase relationship between the two periodic events This could give a very misleading indication of the real average work load Note also that in communication intensive parts of the application the work load can be relatively high even if the application tasks are not very busy This is caused by the communication drivers that are part of the kernel Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 169 Practical hints for correct use 16 Practical hints for correct use 16 1 Flexible use of the messages 16 1 1 General features The Virtuoso message system has been designed to fully support the Vir tual Single Processor Model which is the very essence of Virtuoso To achieve this it has the following key features 1 Messages are synchronous both tasks involved in a message exchange are descheduled until the transfer of data is finished 2 The default action by the kernel is always to copy the message data even if the sen
313. fixed point or floating point data and logical operations on fixed point data ALU instructions are ADI 2 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Analog Devices 21020 DSP a floating point fixed point addition substraction add substract aver age a floating point manipulation binary log scale mantissa fixed point add with carry substract with borrow increment decre ment logical AND OR XOR NOT functions absolute value pass min max clip compare format conversion reciprocal and reciprocal square root The multiplier performs fixed point or floating point multiplication and fixed point multiply accumulate operations Fixed point multiply accumulate operations may be performed with either cumulative addition or cumulative substraction This can be accomplished through parallel operation of the ALU and the multiplier The most important multiplier instructions are m floating point fixed point multiplication floating point fixed point multiply accumulate with addition round ing optional m rounding result register a saturating result register a clearing result register The shifter operates on 32 bit fixed point operands Shifter operations include a shifting and rotating bits a bit manipulation bit set bit clear bit test The register file provides the interface between the processor bus
314. fore the actual service requested by the interrupt handler is called Note ST is included in the Cfree set because it contains the flags tested by the conditional instructions bits 0 6 Other bits in ST have system control functions and should be treated as part of Sysset The Sysset register are used for system and periperhal control only They are never swapped and shoul be regarded as global resources Only very low level routines such as hardware drivers will ever need to access these registers The INTSET registers are those that must have been pushed on the stack when an interrupt handler terminates and wakes up the kernel by calling one of the ENDISR services this is discussed in more detail in the section on interrupt handling below At that point the nanokernel needs some registers to work with It would be a waste of time to pop all registers saved by the ISR only to have to push them again when entering the kernel The registers in Nswap are saved and restored by the nanokernel when swapping processes For the PRLO process assumed to be a C function using i0 as its frame pointer the nanokernel will save and restore i0 in the normal way When a PRHI process is swapped in iO will be set to point to its process control structure A PRHI process can use i0 to access local vari ables created in its workspace and should normally not modify this register ADI 24 Virtuoso Binding Manual Copyright 1996 Eonic Systems Vi
315. g Manual Copyright 1996 Eonic Systems Virtuoso on the Analog Devices 21020 DSP allows the application writer to optimize this important part of their implemen tation Some basic services that will be required for almost all drivers are provided Most low level details have already been described in the previous sections on interrupt handling and communication with the microkernel At the higher level a typical driver can usually be divided into three functional parts 1 The first component is a function to install the driver This should initialize the hardware and any data structures used and install interrupt handlers for the driver A call to this function is usually placed inside a driver statement in the system definition file The SYSGEN utility copies this call into a function named init_drivers it generates in the node c files The init_drivers sub routine is called by kernel_init just before it returns 2 Most drivers will provide one or more subroutines that can be called from the task level and that implement the actual functionality of the driver At some point these functions will call KS_EventW or KS_Wait to make the calling task wait for the completion of the driver action 3 One or more interrupt handlers are required to generate the events or sig nals waited for by these subroutines In the simplest case the only actions required from the ISR will be to service the hardware and to reschedule a waitin
316. g ewa 9 SLHOd NIT 9 SNIS z 101 uog SLYOd TVIYAS s4J3Lsi9J 4 VING J9V4943LNI YOSSJJOYdILTNN uoneynwy 3 SO ovir R Y3LJIHS 7ayYVva Na Op x 91 YaIIdI LIN i ad viva Ov ZE aina sng eea wa yqqv viva viva yqqv 1lY40d O I LHOd YOSSAD0Ud sypojg payodenq uepuadapuy om _ wyus pevog yeng YSONSNODAS INVYSOdd cova ud 8t X ZE AHOVO 8b Nd Sng ed Wd bz a Wwa sna sseippy Nid sng ssaippy Wd zexyxg LOvd pexyxe NOILONYLSNI vam JOSS3901d 2109 x Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 2 2 Virtuoso on the ADSP 2106x SHARC 21 6 Developing ISR routines on the SHARC 21 6 1 General principles When using Virtuoso Classico there are basically 2 types of ISRs that can be used m ISRs that modify the status of a kernel object m ISRs that don t The second type is the easiest to implement as they do not require an inter face to the kernel The ISR consists of 4 parts a Pushing a number of registers on the stack m Performing whatever operation that is necessary Restoring the registers from the stack m Return from the interrupt In this case any register can be used as long as it gets restored to its origi nal value before
317. g task and all data handling and protocol implementation can be done at the task level This method can be used if the interrupt frequency is not too high lt 1000HZ For higher data rates some of the task code should be moved to the ISR in order to reduce the number of task swaps In most cases the actions required from the interrupt handler will not be the same for each interrupt and some form of state machine will have to be implemented into the ISR If the number of possible states grows it is often much easier to use one or more PRHI processes to implement the protocol Processes can wait for interrupts at any number of places in their code and each of these points represents a state of the system As an example the virtuoso network driver have been designed using this method Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 29 Alphabetical List of nanokernel entry points 19 Alphabetical List of nanokernel entry points e BRIEF scape Sas e CLASS e SYNOPSIS e RETURN VALUE In the pages to follow all Virtuoso nanokernel entry points are listed in alphabetical order Most of these are 21020 call some are C callable Brief functional description One of the Virtuoso nanokernel service classes of which it is a member The ANSI C prototype C callable or Assembly language calling sequence The return value if any C callable only e ENTRY CONDITIONS Required conditions before cal
318. g the nanokernel The L_CHAN structure has two fields 0 CH_PROC pointer to the PCS of a waiting process or NULL 1 CH_LIST pointer to first element of the linked list or NULL The nanokernel services that operate on this type are PRHI_GETW wait action PRHI_GET test amp modify action PRHI_PUT signal action 37 4 3 S_CHAN Stack channel This type of channel uses a memory block as a data stack The microkernel uses a Stack channel to input commands from tasks and the network drivers and to receive events from interrupt handlers The S_CHAN structure has three fields 0 CH_PROC pointer to the PCS of a waiting process or NULL 1 CH_BASE pointer to base of the stack 2 CH_NEXT pointer to the next free word on the stack The nanokernel services that operate on this type are PRHI_POPW wait action PRHI POP test amp modify action PRHI_PSH signal action 37 5 Register conventions In order to understand the register conventions adopted by the Virtuoso nanokernel the following register sets should be introduced CSAVE R4 R8 AR3 AR7 DP SP CFREE ST RO R3 R9 R11 ARO AR2 IRO IR1 BK RC RE RS NSWAP AR3 AR5 SP SYSSET DIE IIE IIF IVTP TVTP INTSET ST R11 ARO AR2 The CSAVE and CFREE sets are defined by the procedure calling standard of the C compiler CSAVE is the set of registers that are preserved across a subroutine call if a function uses any of these it must re
319. gister that is saved 7 in the prologue code of the ISR Note that this epilogue code is not critical anymore provided the prologue of all ISRs start with an increment of the Stack Pointer R7 Which registers have to be preserved by an ISR depends on the class of ISR an on which registers are used in the ISR If the ISR stands on its own no signal is made to the kernel only those registers must be preserved that are used by the ISR In this case the prologue and epilogue code just described are to be used In the case the ISR gives a signal to the kernel all registers that are used by the ISR must be preserved except the registers DO L D1 L and RO these registers must always be saved at the start of a signalling ISR regardless if they are used by the ISR or not because the kernel is relying on the fact that they are saved The kernel expects in register DO L the event signal number which can range from 0 to 63 inclusive So for a signalling ISR next conventions must be followed 1 First increment the Stack Pointer R7 Save registers DO L D1 L and RO in this sequence Save all other registers used by the ISR Do whatever has to be done body of ISR Restore all registers except RO D1 L and DO L Note however that the last register restore may NOT contain a decrement of the Stack Pointer because this decrement would be one too much 6 Load register DO L with the event signal number value 0 63 7 Jump t
320. gisters are those that must have been pushed on the stack when an interrupt handler terminates and wakes up the kernel by calling the ENDISR1 service this is discussed in more detail in the section on interrupt handling below At that point the nanokernel needs some registers to work with It would be a waste of time to pop all registers saved by the ISR only to have to push them again when entering the kernel The registers in NSWAP are saved and restored by the nanokernel when swapping processes For the PRLO process assumed to be a C function using i3 as its frame pointer the nanokernel will save and restore i3 in the normal way When a PRHI process is swapped in i3 will be set to point to its process control structure A PRHI process can use i3 to access local vari ables created in its workspace and should normally not modify this register If it does the initial value can always be reloaded from NANOK_PRHI 13 must point to the PCS whenever the process calls a nanokernel service and when it terminates The NSWAP register set is always available but note the special use of i3 If a PRHI process is swapped in as the result of a C function call by the PRLO process then the CFREE set is available for use by the PRHI pro cess This means that the process can safely call any C function It should of course save those registers in CFREE that it wants to preserve across the call If a PRHI process is swapped in as the result of an inter
321. h the outside world using a predefined mechanism Conceptually tasks must be looked upon as executing simultaneously or overlapping in time This means that on a single processor a task switching algorithm has to be implemented because the processor can only execute one thing at a time and the concurrent behavior of the tasks must be simu lated For a long time processors were rather slow so that task switching was a heavy operation Current microprocessors are much better at it and some like the transputer even have direct support in hardware for doing it Never theless real time kernels were brought to the market to provide this kind of solution in a generic way In the solutions above priorities are used by the task scheduler because dealing directly with time bound constraints is very difficult Some better algorithms deal directly with time by using a deadline scheduler This kind of scheduler assigns the processor to the task with the nearest deadline This algorithm can also provide better performance under higher processor loads The Extended and Dynamic Support Package of Virtuoso will use this kind of scheduler 4 4 The high demands of Digital Signal Processing Digital Signal Processing often impose demands that cannot be fulfilled by traditional processors Therefore Digital Signal Processors DSPs have architectures that enable faster execution of algorithms combined with fast handling of interrupts As a result most DSPs have
322. he advantage is that no further synchroni zation is required between the enqueuing and the dequeuing task permitting the enqueuer to continue unless the queue was full Another advantage of this mechanism is that a queue also acts as a port For example to access the console from any node in the system one simply enqueues or dequeues the queue that is associated with the console If used in conjunction with a resource to ensure the atomicity of the protocol this permits easy imple P1 32 Virtuoso User Manual Copyright 1996 Eonic Systems Functional support from Virtuoso mentation of a distributed service such as the graphical server that comes with Virtuoso While the single processor version impose no limit on the size of the ele ments in the distributed version the size of the entries have been limited to 24 bytes for performance reasons Buffered communication for larger sizes can easily be handled by combining queues to pass the parameters and to use the KS_MoveData to move the actual data FIFO QUEUE 5 4 3 2 FIGURE 10 A FIFO queue acts as an ordered buffer between tasks This summarizes the normal microkernel objects that are used at the task level to implement an application Virtuoso also provides a set of additional functions that can be used in conjunction These are categorized in two classes 4 7 9 Class Special These include less trivial operations Th
323. he current palette The palette determines the mapping of color numbers to visual colors The coding depends heavily on the selected driver and mode For details see GRINT H and documentation sup plied with your hardware void getallpalette struct palette pal Reads the current palette void setpalette int colornum int color Sets the current color mapping for one color only void setrgbpalette int color int r int g int b As setpalette but for the IBM 8514 adapter driver 6 only P2 134 Virtuoso Reference Manual Copyright 1996 Eonic Systems Runtime libraries void setfillstyle struct fillstyle fstyle The fillstyle determines how filled object are plotted You can select the color to be used a number of standard patterns or set a user fill pattern The user fill pattern is an 8 by 8 pixel pattern represented as an 8 character array See GRINT H for parameter details void getfillstyle struct fillstyle fstyle Reads the current fillstyle void getuserpars struct userpars upars Reads the current user parameters See the USERPARS typedef for details There is no corresponding setuserpars these values can be set by the five next calls documented below void setcolor int color Sets the current line and text color The solid filling color is set by the setfillstyle function void setbkcolor int color Sets the current background color void setlinestyle int style
324. he essential module P1 10 Classes of microkernel services eccceeeeceeeeeeeeeeeeeeeees ceseeeees enneeeeeenneeees Pi 11 The object as the unit of distribution 22 eee ce eeece ee eeeeeeteeeeseeeeeeeeeees P1 11 A multi level approach for speed and flexibility eee ceeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeees P1 13 An execution trace illustrated ce cceeseeeeeeeneeeceeee eens eeeseeeeeeceeesnsee snseeeneeaneeeees P1 16 Pr cessor Specific SUPPOM a es cel wiles acct sei ahaa aii P1 17 Functional support from Virtuoso P1 18 WAL FOGUUIGHI ON ssrin eanne EE EEE EK EEA Ea aE AEAEE AAA TERES P1 18 Parallel processing the next logical step 0 eee ceeeeeeeeeeeeeeeeeeeeee tees eeeaeeeeeeeenees P1 18 What is hard real time ci seee ecces thecee decavtaeeteeden ety exvag ors desaveness nuca qeeieeoceest marenee P1 20 The high demands of Digital Signal Processing ccc ceeeeeeeeeeeeeeaeeeeeneeaeeeees P1 21 A frs COU ISI OU os 2 sce ec Nee ct cee eins cats cdaiae seca aa E a E e aa Aa a eee P1 22 Parallel programming the natural Way e ceceeeeeceee cere eeeeeeeeeeeeeeeseesseeeeeeeeeeee P1 22 About objects and services Sik iste eteetlec ages Al tiedes eee eas aac cenedasaenas aes eet P1 23 The Virtuoso microkernel objects and the related Services e P1 23 MASS CASI EE E oct ct ame AE tee aca adc recede teagan Gre een eae etee P1 23 The task as a unit Of execution
325. he kernel service originating task which entails sometimes an extra context switch Timings were made with the Logical Systems compiler and with the monitor disabled Minimum Virtuoso kernel call 13 us Average allocate or deallocate 17 us enqueue 1 byte 22 us dequeue 1 byte 29 us enqueue 4 bytes 23 us dequeue 4 bytes 23 us signal semaphore 17 us average lock and unlock of a resource 17 us enqueue 1 byte to waiting higher priority task dequeue in waiting task 83 us send message to higher priority task wait for acknowledgment 83 us send message to lower priority task wait for acknowledgment 85 us signal wait and wait signal handshake between two tasks 71us TABLE 2 Table 2 Performance Figures for Virtuoso v 3 0 calls at 30 MHz 33 11 2 The distributed version The benchmarks indicate that the interrupt response times are only slightly increased by the fact that a service is located on a remote processor even if the call is forwarded using an intermediate node As such each intermediate node adds less than 50 microseconds to the interrupt response times How ever different dynamic effects can have an importance such as 1 communication latency 2 time varying workloads 3 lack of buffers to store suspended calls In the design of the distributed version which mainly consisted in adding an embedded router to the kernel special care was taking to minimize above mentioned effects For this reason all ke
326. he system sometimes called the nulltask This task is created automatically by the kernel and it is in fact task N 1 not zero In the mon itor listings it is shown as idle It is in fact the continuation of the C main function after it has installed the kernel and started the user tasks The nulltask code is little more than an endless loop counting its own num ber of iterations By reading the iteration counter at times t0 and t1 we can determine the amount of time Ti a processor has been idle during the inter val tO t1 The workload is then calculated as follows W 1 Ti tl t0 The kernel function KS Workload actually returns the integer value 1000 W P2 168 Virtuoso Reference Manual Copyright 1996 Eonic Systems Debugging environment under Virtuoso The measuring interval can be changed by a calling the kernel function KS_SetWlperiod T The default value is 100 ms while legal values for T range from 10 to 1000 ms Every T ms the kernel takes a look at the itera tion counter in the nulltask It keeps a record of the two most recent values and of the times when these were read When workload is called the returned value is computed from the current time and iteration count and the values taken at the start of the last full interval The actual measuring period can therefore be any value from T to 2T To obtain meaningful results the workload measuring interval should be sig ni
327. he timer value are m KS _HighTimer a KS _LowTimer In high resolution the number of timer counts are returned On the 21060 the count is equal to a period of the clock frequency In low resolution the number of kernel ticks are returned A kernel tick is a multiple of timer count and defined in the main function As this value is a 32 bit wraparound value it is more interesting to calculate the difference between two values read out consecutively However to facilitate this ker nel service KS_Elapse is written for this purpose See the Alphabetical List of Virtuoso kernel services earlier in this manual for a full description of these kernel services Event number 48 is reserved exclusively for the timer device driver ADI 2 36 Virtuoso Binding Manual Copyright 1996 Eonic Systems Predefined drivers 23 1 2 The host interface device driver Two host interface drivers are currently available m void BW21k_host int irq_num m void Alex21k_host int irq_num The former is used for all currently supported Bittware boards EZ Lab Snaggletooth and Blacktip while the latter is to be used for the ALEX Com puter Systems SHARC1000 board The use of the host interface device driver is required on the root if the host services are to be used The parameter passed to the driver is the IRQ number on which the ISR is to be installed For the Bittware and Alex boards this value should be 8 by default For more d
328. hed as the associated timer doesn t run For this reason the ISR adjusts from time to time the correct time in the 18 2 Hz timer 26 2 Warning when using Virtuoso on a PC When you use Virtuoso on a PC you must be aware that DOS is still there to provide access to the host resources such as the disk The problem is that whenever you issue a service request to DOS you enter a critical section and all kernel activity is suspended For example when you write a file DOS initiates an access to the disk As long as this operation is not finished DOS waits So while you can use Virtuoso to develop the logic of a real time application you can t really use it to build a hard real time application on a PC This can only be achieved on boards that don t require DOS Note that none of the real time kernels on the market achieve this Whatever solution is chosen it can t solve the fundamental problem that DOS is sitting there At best you can use a real time kernel on a PC to achieve a soft real time appli cation unless you don t make any DOS call In Virtuoso DOS services stdio and graphics are accessed through a DOS server task This task is normally defined with the highest priority Copyright 1996 Eonic Systems Virtuoso Binding Manual 11 1 Virtuoso on the Intel 80x86 l1 2 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Motorola 56K DSP 27 Virtuoso on the Motorola 56K DSP 27 1 Virtuoso ve
329. hese parallel processing resources Many instructions allow the program mer to keep each unit busy thus enhancing program execution speed The programming model is shown in FIGURE 17 and FIGURE 18 The ten Data ALU registers DO D9 are 96 bits wide and may be treated as 30 independent 32 bit registers or as ten 96 bit floating point registers Each 96 bit register is divided into 3 sub registers high middle and low The eight address registers RO R7 are 32 bits wide and may contain addresses or general purpose data The 32 bit address in a selected address register is used in the calculation of the effective address of an oper and The eight offset registers NO N7 are 32 bits wide and may contain offset values used to increment and decrement the corresponding address regis ters in address register update calculations or they may be used for general purpose storage The eight modifier registers MO M7 are 32 bits wide and may contain val ues which specify address arithmetic types used in address register update calculations i e linear reverse carry and modulo or they may be used for general purpose storage When specifying modulo arithmetic a modifier reg ister will also specify the modulo value to be used The Status Register is a 32 bit register consisting of an 8 bit Mode register MR an 8 bit IEEE Exception register IER an 8 bit Exception register Copyright 1996 Eonic Systems Virtuoso Binding Manual M3 3 Vi
330. his speed Therefore interrupt handlers cannot always be implemented as a task The interrupt processing mechanism implemented in Virtuoso is designed to separate interrupt handling into two distinct parts The first part is done entirely in the background without any support from the kernel This would typically be the code required to service the hardware that generated the interrupt or to buffer data generated by high frequency interrupts The second part is the one that is not related to the hardware but to the logic of an application As an example special action may be required when a received message is complete Virtuoso encourages the application writer to do this part of interrupt processing at the task level by providing a fast and easy to use mechanism to transfer control from an ISR to the kernel and indirectly to a task If an interrupt occurs at a frequency that can be han dled at the task level then only a very simple ISR an example is supplied is necessary to transfer control to a task This approach has a number of important advantages Copyright 1996 Eonic Systems Virtuoso Binding Manual TIl 7 Virtuoso on the Texas Instruments TMS320C30 amp C31 When the thread of execution of an ISR enters the kernel it is no longer an ISR The interrupt service routine has effectively ended This is so because the kernel entry point used by ISR s is fully reentrant and processing inside the kernel is performed
331. hs You need a path to the C compiler e g tic440 the libraries lib and to the directory of executable programs bin When using the PC graphics library you also need to set up a path to the Borland graphics driver e g bc bgi In the examples directory you can find small test programs It is advised to copy one of these into your own directory if you start programming IMPORTANT NOTE As your board might have a different memory lay out and interprocessor connections than those used to build the examples please verify the mem ory layout and interprocessor connections if any so that they reflect your own board and remake the examples Each directory is delivered with a makefile Borland make exe compatible make will generate a new binary make install will copy the libraries to the lib directory make clean will remove all files that can be regenerated Copyright 1996 Eonic Systems Virtuoso User Manual P1 3 Installation 1 2 1 3 Kernel libraries provided The following libraries are provided The Virtuoso kernel 1 VIRTOS LIB no support for the task level debugger 2 VIRTOSD LIB with support for the task level debugger Host access 1 CONIO LIB simple console I O mainly used for terminal I O 2 STDIO LIB C style I O 3 BGI LIB Borland BGI graphics calls To recompile the libraries go to the SOURCE Virtuoso directory and type MAKE This will display instruct
332. ia P2 4 Task group SOU sieniin iaket aAA AA ARa AAAA K ESPRE TEAS P2 4 TASK Stat sec estesere cares dic esd e Eaa Ea a NEE Naa e ENR Aet E RE Siint P2 4 DRE ELC 01A EAEE E E E A ET P2 5 Task Abort Handler isciu urripen toa ar ea A AE nT P2 5 EEE e AE EE A N 2 as P2 5 Task ONS sense eases a e ae a a A dee te P2 5 ETAT ola OE e eE EEEE E E E EEN EA E E cee wh E E eee P2 5 Mail DOKE S rin as aide e E a A EAA ER ag TA E O ER a aa aa aae tetat P2 6 QUEUES Sno aue a aT a a T e Ea lens ENA P2 8 ROSOUrCES ainireti aa AE AN AAE E a anA A AAE EE E ATE aat P2 8 TATA GUS EE E AAEE ET ET EE TT P2 9 Memory MAPS oetcscacecctiestise cpkcicnindeesilevagusteedereuteviane cis aaa N AAA EAE EAE a RES i eiii P2 10 Virtuoso microkernel services P2 11 Short OV OIG W a e a a 2 peu gence we E EE ear STE E ace PE Pewee P2 11 PD OM ANT Note siene deal aeee joes aa ce tpeadeccw EAEE N EAE AEE aaas P2 11 Task control microkernel services 2 ccceeseceeeecceee ce eeeeeeee eeeeee eee eeseseeeeneeeeneee renne P2 12 Semaphore microkernel services ceceeeeeececeeeeeeceeeeeeeeeceseeeeeeeeeeaeeeeeeneeeeeeens P2 13 Mailbox microkernel services ickitee veces eeereepeedeiirrs dle eee Mader ae P2 14 Queue microkernel services ccciceieciecatsscaeeiehelesined de see adeniaddenateaeee eared P2 15 Timer management microkernel services cceeeeesecceeeeeeeeeeeeeeeeeeeeeeeeseneeeeeeees P2 16 Resource management microkernel services 0 2
333. ic Systems or your distributor P2 176 Virtuoso Reference Manual Copyright 1996 Eonic Systems Microkernel C interface 17 Microkernel C interface 17 1 Microkernel C classes In section 7 1 on page 3 an overview was given of the microkernel objects and their services The C interface for the microkernel provides a tighter coupling between an object type and its services Also global C objects representing each kernel object defined by the user in the sysdef file can be generated automatically by the sysgen tool The following table indicates the relationship between kernel object types and the corresponding C class that encapsulates these objects Kernel Object Type Related C class es Tasks KTask KActiveTask Task Groups KTaskGroup Semaphores KSemaphore Mailboxes KMailBox Queues KQueue Memory Maps KMemoryMap Resources KResource Timers KTimer At this moment no C class has been provided for encapsulating sema phore lists One extra class is available that provides a C shell for the KMSG datastructure This class is named KMessage The C classes have been designed to introduce minimal overhead both in memory usage code and data size and run time behavior This is accom plished by making extensive use of inlined functions In the following section we will indicate how sysgen takes care of generating the C objects corresponding to the ones defined by the user in the sysdef file Ther
334. ied task groups Task void KS_LeaveG K_TGROUP This microkernel service clears the specified taskgroup bits in the task group identifier NONE KS_LeaveG ABORT_GRP KS_JoinG KS_LeaveG KS_Groupld This service is currently implemented as a macro and cannot cause a task switch Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 55 Alphabetical List of Virtuoso microkernel services 11 27 e SUMMARY e CLASS e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES KS Linkin Start to read a datablock from a link and continue Processor specific int KS_Linkin int link int size void datablock This call reads data from a processor link The call returns immediately with no descheduling of the calling task It is possible to wait on the termination of this event at a later stage of the program Event number LinkEventl LinkEvent2 lock1 20 Block2 20 in in Gr et ct w in inkEventl KS_Linkin 1 20 Blockl inkEvent2 KS_Linkin 2 20 Block2 other code not using Block x wait for data to be read ae KS_EventW LinkEvent1 KS_EventwW LinkEvent2 KS_LinkinW KS_LinkinWT KS_Linkout KS_linkoutW KS_LinkoutWT iface h Attempting to read from a link without using this service may cause unpre P2 56 Virtuoso R
335. ifying the size parameter on systems where characters are stored one per word or where sizeof does not return the number of 8 bit bytes in a type P2 62 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services 11 31 e SUMMARY e CLASS Saw es e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES KS_LinkoutW Write a datablock to a link with wait Processor specific void KS_LinkoutW int link int size void datablock This call writes data to a processor link The call returns when the writing of the datablock has finished Meanwhile the calling task is put into the LINK WAIT state NONE static char chanmessage This is a test message n int msgsize msgsize strlen chanmessage KS_LinkoutW 3 msgsize chanmessage KS_Linkout KS_LinkoutWT KS_LinkinW KS_linkinWT iface h Attempting to read from a link without using this service may cause unpre dictable side effects on some processors The size parameter is the number of 8 bit bytes to be written Care needs to be taken when specifying the size parameter on systems where characters are stored one per word or where sizeof does not return the number of 8 bit bytes in a type Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 63 Alphabetical List of Virtuoso microkernel services 11 32 e SUMMARY e CLAS
336. ignal WaitTimeout 2 70 Signal WaitMany 2 3 74 Signal WaitManyTimeout 2 3 92 Resources Lock or Unlock 1 16 Note One byte is one 24 bit word on the DSP56000 1 involves no context switch 2 involves two context switches Timing is round trip time 3 Length of semaphore list is 2 Application development hints The easiest way to start is to copy and modify one of the supplied examples Some of the necessary files have fixed names so each application should be put in a separate directory M1 26 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Motorola 56K DSP The following files will be needed for each application SYSDEF The VIRTUOSO system definition file The SYSGEN utility will read this file and generate NODE1 C and NODE1 H MAIN1 C This contains some more configuration options and the C main function Copy from one of the examples A number of configuration options are defined in this file so they can be changed without requiring recompilation of all sources this would be neces sary if SYSDEF is modified CLCKFREQ this should be defined to be the clock frequency of the hard ware timer used to generate the TICKS time TIICKTIME the TICK period in microseconds TIICKUNIT the TICK period in CLCKFREQ units TICKFREQ the TICK frequency in Hertz The number of available timers command packets and multiple wait packets are also defined in this f
337. ile How much you need of each depends on your application but the following guidelines may be followed Timers are used to implement time outs at most one per task and can also be allocated by a task A command packet will be needed for each timer allocated by a task Com mand packets used for calling a kernel service are created on the caller s stack and should not be predefined A multiple wait packet will be needed for each semaphore in a KS_WaitM service call for as long as it remains waiting MAIN1 C also defines some variables used by the console driver tasks the clock system the debugger task and the graphics system These are included automatically if you use the standard names for the required kernel objects CRTO56I ASM start up assembly code Copyright 1996 Eonic Systems Virtuoso Binding Manual M1 27 Virtuoso on the Motorola 56K DSP MAKEFILE The makefiles supplied in the EXAMPLES directory can easily be modified for your application They also show how to organize things so you can optionally include the task level debugger If you want to include the task level debugger put the corresponding definitions out of comment VIRTLIB LIBS virtosd lib DD dDEBUG DDD P DEBUG and put the other definition in comment VIRTLIB LIBS virtos lib whereby is the comment sign Then remake the application just by doing MAKE
338. ill have unpredictable side effects Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 91 Alphabetical List of Virtuoso microkernel services 11 54 SUMMARY e CLASS ey ea e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES KS _ SetPrio Change the priority of a task Task void KS_SetPrio K_TASK task int priority The KS_SetPrio microkernel service will change the priority of the specified task A task switch will occur if the calling task is no longer the highest prior ity runable task NONE int MyPrio yPrio KS_TaskPrio save my priority KS_SetPrio KS_TaskId 3 raise my priority KS_Lock FILERES readfile KS Unlock FILERES KS_SetPrio KS_TaskId MyPrio reset my priority KS_TaskPrio This microkernel service does not modify the order of insertion in any of the waiting lists If KS_SetPrio is used to raise the probability of becoming run able if must be used before invoking the desired microkernel service Gener ally speaking changing the priority of a task must be used with caution and only used for addressing time limited scheduling problems A low numeric value is a high priority Thus the highest priority task has a priority of one P2 92 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services 1
339. in macro h e DESCRIPTION If a process is waiting for the channel the pointer to the packet is passed on and the waiting process is rescheduled Otherwise the packet is linked in at the head of the list In either case control returns to the caller e ENTRY CONDITIONS i4 pointer to channel r2 pointer to packet to add to the list e EXIT CONDITIONS rO r1 r8 i4 ASTST are corrupted EXAMPLE include macro h i4 dm CHANNEL r2 dm PACKET PRHI_PUT the packet is added to the list SEEALSO PRHI_GET PRHI_LGETW e SPECIAL NOTES This entry point must not by called from the low priority context but it can be used by interrupt handlers The first word of the packet is used as a link pointer and will be overwritten Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 2 29 Alphabetical List of nanokernel entry points 22 11 PRHI_ PSH e BRIEF Push a word on a stack channel e CLASS Process communication e SYNOPSIS PRHI_PSH PRHI_PSH is defined in macro h e DESCRIPTION Ifa process is waiting for the channel the data word is passed on and the waiting process is rescheduled Otherwise the data word is pushed on the stack In either case control returns to the caller e ENTRY CONDITIONS i4 pointer to channel r2 data word to push e EXIT CONDITIONS rO r1 r4 and r8 are corrupted All other registers are preserved EXAMPLE i
340. in the wait list in order of their priority they had at the moment the wait state was entered The figure below illustrates the possible Task states and the transition possi bilities Copyright 1996 Eonic Systems Virtuoso User Manual P1 25 Functional support from Virtuoso SCHEDULED RUNNING KS_AnyServiceW T KS_ Start DESCHEDULED KS_Yield RUNABLE J WAIT_END WAITING KS Suspend KS_ Resume KS Resume warn amp SUSPENDED WAIT _ KS Abort ABORTED For equal priority Tasks Can be coexisting FIGURE 4 4 7 3 Task state transition diagram In normal conditions tasks should never terminate unless the system s oper ation as a whole is terminated because the application requires it Therefore aborting a task needs to be done with the right precautions When a task is aborted all traces of its previous execution should be cleared from the sys tem As such this is a service only to be used with care as it not only takes much time but the application must be written so that this operation will not generate any unexpected side effects like tasks waiting on messages from the aborted task While the Virtuoso microkernel can clear the task the application might require specific actions This is handled with the KS_Aborted service call When used the microkernel will save the specified task aborting entry point in a separate area When the task is aborted Virtu oso transfers control t
341. ined in TRAPS INC If a process is waiting on the channel the pointer to the packet is passed on and the waiting process is rescheduled Otherwise the packet is linked in at the head of the list In either case control returns to the caller AR1 pointer to channel AR2 pointer to packet to add to the list ARO AR1 R11 and ST are corrupted All other registers are preserved include traps inc assume AR5 points to a parameter struct assume ARO points to packet to add to the list lat PRHI_PUT ldi tar5 FREE_LIST arl ldi ar0 ar2 nop the packet is added to the list PRHI_GET PRHI_GETW This entry point must not by called from the low priority context but it can be used by interrupt handlers The first word of the packet is used as a link pointer and will be overwritten TI2 36 Virtuoso Binding Manual Copyright 1996 Eonic Systems Alphabetical List of nanokernel entry points 38 13 BRIEF 55 acer e CLASS 2 Saw es e SYNOPSIS e DESCRIPTION e ENTRY CONDITIONS e EXIT CONDITIONS EXAMPLE SEEALSO e SPECIAL NOTES PRHI_ PSH Push a word on a stack channel Process communication LATcond PRHI_PSH PRHI_PSH is defined in TRAPS INC If a process is waiting on the channel the data word is passed on and the waiting process is rescheduled Otherwise the data word is pushed on the stack In either case control returns to the caller AR1
342. ing Manual Copyright 1996 Eonic Systems Virtuoso on the Analog Devices 21020 DSP 18 9 Developing ISR routines on the 21020 18 9 1 Installing an ISR routine The best place to install and enable an interrupt service routine ISR is in the main function where predefined drivers like the driver for the timer interrupt are installed and enabled It is possible that additional initialisation of registers and or peripheral I O has to be done The best way is to write a C callable procedure that does the necessary additional initialisations and call this procedure after the call to KS_EnableISR An example of this method is the installation of the timer ISR in procedure main include iface h extern void timerO_irgh void extern void timerO_init void int main void init_server KS_EnableISR 4 timerOQ_irgh timerO_init Note In VIRTUOSO CLASSICO there is a function provided that does the work timerO_drv This function installs and initialises the timer The host interrupt service routine is installed and enabled by using the function init_server 18 9 2 Writing an ISR routine A VIRTUOSO MICRO It is very easy to develop ISR routines for the ADSP 21020 You just have to keep the right things in mind An example of an ISR is given and explained below example 1 signalling ISR Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 15 Virtuoso on
343. interface device driver ADI 49 ADI 37 The nanokernel on the 21020 ADI 18 ADI 7 The timer device driver ADI 48 ADI 36 Timer GLO 3 Timer management P2 16 Timers P2 9 Copyright 1996 Eonic Systems TMS320C40 TI2 1 TMS320C40 Chip Architecture TI1 2 TI2 2 TMS320C40 Software Architecture TII 3 TI2 3 Tracing monitor P2 160 trademarks INT 6 tutorial P1 18 U ungetc P2 129 unit of distribution P1 11 unlink P2 130 USTAT ADI 10 V Version of the compiler ADI 10 ADI 1 vfprintf P2 130 Virtuoso history INT 7 Virtuoso implementations on the 21020 ADI 1 Virtuoso on the Analog Devices 21020 DSP ADI 1 vsprintf P2 131 W Workload Monitor P2 168 Writing an ISR routine ADI 15 ADI 4 Y Yield GLO 4 Copyright 1996 Eonic Systems
344. interrupt handler terminates and wakes up the kernel by calling one of the ENDISR services this is discussed in more detail in the section on interrupt handling below At that point the nanokernel needs some registers to work with It would be a waste of time to pop all registers saved by the ISR only to have to push them again when entering the kernel The registers in NSWAP are saved and restored by the nanokernel when swapping processes For the PRLO process assumed to be a C function using AR as its frame pointer the nanokernel will save and restore AR3 in the normal way When a PRHI process is swapped in AR3 will be set to point to its process control structure A PRHI process can use AR3 to access local variables created in its workspace and should normally not modify this register If it does the initial value can always be reloaded from NANOK_PRHI AR3 must point to the PCS whenever the process calls a nanokernel service and when it terminates Given these definitions it is now possible to determine which registers can be used by a PRHI process and how it should call C functions if this is required The NSWAP set is always available but note the special use of AR3 If a PRHI process is swapped in as the result of a C function call by the PRLO process then the CFREE set is available for use by the PRHI pro cess This means that the process can safely call any C function It should of course save those registers in CFREE that
345. ions Single processor operation In practice the microkernel is like a part of the runtime library of the compiler with the difference that we are really talking about tasks and not just func tions The user must consider the microkernel as an activity with a higher pri ority than any of his application tasks The microkernel is therefore written to act upon events as fast as possible minimizing the time that is spent in the microkernel As such whenever anything happens in the system that awakes the microkernel the task status can change The result is that at this moment the microkernel will determine whether the current task is still run able or whether any other task with a higher priority has become runable If so the microkernel will switch the context to this task If no other processors are involved in a microkernel service the operation is as follows When call ing a microkernel service the application task actually calls a microkernel interface function In this interface the parameters of the required service are copied to a parameter area and the microkernel is awakened by an inter P1 38 Virtuoso User Manual Copyright 1996 Eonic Systems Functional support from Virtuoso rupt The microkernel will then examine the call and execute the required actions Eventually a task swap can result The microkernel can also be awakened by other sources such as a timed event an interrupt generated by external hardware or by da
346. ions on how to proceed Note Other libraries are provided as well These are target dependent See the relevant sections or the readme files Confidence test 1 Change to the EXAMPLES directory cd VIRTUOSO EXAMPLES D1P Note that dip is called demoip on older releases 2 The sysdef definition file for the different system objects is already given From these Sysgen will construct the C files and H files needed for compila tion Just invoke your text editor and view the definition file 3 The different object definitions can now be viewed For a better under standing it is advised to have a quick look at the relevant section in Part2 of the manual 4 After viewing the system definition file you can invoke the Sysgen system generation utility on the file This generates automatically all include files There is a node c and a node h file for each processor in the system You can try as follows make This will call the make utility that operates on the makefile This will parse the system definition file compile link and configure the test program P1 4 Virtuoso User Manual Copyright 1996 Eonic Systems Installation 5 Run the final demonstration program using one of the supplied bat pro gram For example run test This starts up the server program on the host and boots the demonstration program onto the root processor For example host_x rlsz test nli Foll
347. iority nanokernel process It must be called from the C main function or by a microkernel task only ADI 2 20 Virtuoso Binding Manual Copyright 1996 Eonic Systems Alphabetical List of nanokernel entry points 22 2 ENDISR1 BRIEF Terminates an ISR and conditionally invokes the process swapper e CLASS Interrupt service management e SYNOPSYS ENDISR1 ENDISR 1 is defined in macro h e DESCRIPTION This entry point must be called to terminate an ISR A nanokernel process swap is performed IFF m the calling ISR interrupted the PRLO process m a high priority process is ready to execute m there are no more nested interrupts e ENTRY CONDITIONSThe ISR should have saved the interrupted context so that the exit sequence listed below would correctly terminate the ISR e EXIT CONDITIONS This call terminates the ISR and does not return EXAMPLE SEEALSO e SPECIAL NOTES Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 2 21 Alphabetical List of nanokernel entry points 22 3 K_taskcall e BRIEF Senda command packet to the microkernel process e CLASS Process communication e SYNOPSYS void K_taskcall K_ARGS A e DESCRIPTION This C callable function is used by all KS_ services to send command pack ets to the microkernel process e RETURN VALUE none EXAMPLE SEEALSO PRLO_PSH e SPECIAL NOTES This function mus
348. irable side effects In future versions this variable may become read only or be replaced by a func tion call P2 72 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services 11 40 e SUMMARY e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES KS PurgeQueue Purge the queue of all entries Queue void KS_PurgeQueue K_QUEUE queue The KS_PurgeQueue microkernel service forces a queue to a known EMPTY state The KS_Enqueue waiting list is purged of all waiters and all entries are discarded NONE K QUEUE DATAQ K TASK PUTTER GETTER KS_PurgeQueue DATAQ reset DATAQ to empty and restart the tasks KS_Start PUTTER start producer task KS_Start GETTER start consumer task KS_InqQueue Waiting tasks will receive RC_OK when they are restarted This will be changed in a future version to the correct value RC_FAIL Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 73 Alphabetical List of Virtuoso microkernel services 11 41 e SUMMARY e CLASS es es ee e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE KS Receive Receive a message Mailbox int KS_ Receive K_MBOX mailbox K_MSG msgstruc The KS_Receive message microkernel service is used to retrieve a
349. ircumstances prioritizing is essential to preserve the real time nature of the kernel P2 170 Virtuoso Reference Manual Copyright 1996 Eonic Systems Practical hints for correct use 16 1 2 Mailboxes When two tasks want to exchange a message they do not talk to each other directly They will both use the services of an intermediate object called a mailbox Mailboxes provide a degree of isolation between the two parties involved in a data transfer As an example a mailbox could be associated with a device Tasks wishing to use the device would then not need to know the task identity of the device driver This could even change at run time with out the clients of the device being aware of the replacement Note also that a mailbox can reside on a processor node where neither the sender nor the receiver reside A mailbox acts as a meeting place for tasks wishing to transmit or receive a message It maintains two waiting lists one for senders and one for receiv ers When a new send or receive request arrives the mailbox searches one of the lists for a corresponding request of the other type If a match is found it is removed from the waiting list and the data transfer is started When this has finished both tasks are allowed to resume execution If no match can be found the caller is suspended and put on a waiting list or the operation fails In above scheme one should consider the data copy as a side effect o
350. is not empty the top element is removed and returned to the caller If the stack is empty the calling process is swapped out and set to wait on the channel It will be rescheduled by the next call to the PRHI_PSH ser vice on the same channel i4 pointer to stack channel struct 10 pointer to PCS of calling process il element removed from the stack r0 rl r8 are corrupted include macro h i4 dm CHANNEL PRHI_POPW PRHI_POP PRHI_PSH This service must not be called from the low priority context or by an isr Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 41 Alphabetical List of nanokernel entry points 19 11 e BRIEF scape Seas e GLASS eae ee e SYNOPSIS e DESCRIPTION e ENTRY CONDITIONS e EXIT CONDITIONS EXAMPLE SEEALSO e SPECIAL NOTES PRHI_ PUT Add a packet to a linked list channel Process communication PRHI_ PUT PRHI_PUT is defined in macro h If a process is waiting on the channel the pointer to the packet is passed on and the waiting process is rescheduled Otherwise the packet is linked in at the head of the list In either case control returns to the caller i4 pointer to channel r2 pointer to packet to add to the list r0 rl r8 are corrupted All other registers are preserved include macro h i4 dm CHANNEL r2 dm PACKET PRHI_PUT the packet is added to the list PRHI_GET PRHI_LGET
351. is used in an attempt to restart a task that is already running the result is unpredictable but almost certainly not what was wanted Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 99 Alphabetical List of Virtuoso microkernel services 11 62 e SUMMARY e CLASS es es eae e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES KS _ StartTimer Start a timer Timer void KS_StartTimer K_TIMER timer K_TICKS delay K_TICKS cyclic_period K_SEMA sema KS_StartTimer starts the timer with an initial delay specified in ticks one shot operation and from then on with an optional cyclic period The sema phore will be signalled each time the timer triggers NONE K_TICKS timer4 K_SEMA MySema timer4 KS_AllocTimer signal Mysema after 100 ticks and then every 20 ticks KS_StartTimer timer4 100 20 MySema KS_RestartTimer KS_StopTimer The delay and cyclic period should be greater than zero or unpredictable side effects may occur P2 100 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services 11 63 KS StopTimer e SUMMARY Stop a timer e CLASS Timer e SYNOPSIS void KS_StopTimer K_TIMER timer e DESCRIPTION KS_StopTimer removes an active timer from the timer queue If the timer has already expired this
352. ith a detailed discus sion of the way the Virtuoso kernel works how to use the kernel services and how to use the Virtuoso development tools PART 3 Virtuoso Binding Manual Part 3 of this manual contains the specific information about installing and using a given Virtuoso implementation for a given target processor with a given C compiler As this information may vary for different combinations of processors and compilers the contents of this part depends on the particular combination you have licensed Other manuals include Virtuoso Technical Notes Virtuoso Modulo 0 VI Copyright 1996 Eonic Systems Virtuoso User Manual INT 9 Manual Format INT 10 Virtuoso User Manual Copyright 1996 Eonic Systems License agreement License agreement EONIC SYSTEMS agrees to grant upon payment of fee to the undersigned CUSTOMER and CUSTOMER agrees to accept a non transferrable and non exclusive license to use the Software hereinafter referred to as the Licensed Product as listed in the license registration form and subject license registration form is attached hereto and made a part of this Agree ment In case of doubt the items as mentioned on the invoice upon delivery of the Software shall be taken as the Licensed Product OWNERSHIP AND CONDITIONS 1 OWNERSHIP Customer acknowledges that Eonic Systems retains all rights title and inter est in and to the Licensed Product and all related materials are and shall
353. ituations can happen When the semaphore count is greater than zero the count is decremented by one and the waiting task continues its execution Otherwise the task is put into the semaphore Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 5 Virtuoso microkernel types amp data structures 7 4 waiting list in order of its priority When the semaphore is then signalled the task with the highest priority is removed from the waiting list This algorithm requires that the semantic meaning given to the event associated by the semaphore is totally independent of the order in which tasks signal the semaphore or wait on it Virtuoso permits to signal a list of semaphores in a single operation while a task can wait for any semaphore in a list of semaphores to be signalled If more than one is signalled the first signalled on the list is taken Semaphores are typically used to synchronize tasks to the occurrence of a given event One task may need to wait for the other to reach a certain point before it can continue Input output operations are an example of this type of synchronization For instance when an input operation is desired the task waits on the input to complete the event by associating the event with a particular semaphore and suspending further processing until the the semaphore is signalled When the input operation is completed the device driver signals the semaphore associated with the event to indicate that the
354. iva P2 174 Virtuoso Reference Manual Copyright 1996 Eonic Systems Practical hints for correct use lent to communicate between the different Virtuoso tasks So it is best to keep this interaction as simple as possible preferably under the form of block transfers The reason is first of all that you are talking to the naked hardware just as you would do without support from the kernel So both receiving and sending tasks need to speak the same protocol If for example the length of the block sent is different from the length of the message received the com munication might stall and never terminate Normally this is called deadlock Normally you can detect this with the debugger Note however that the debugger can only be used on the root processor while with the distributed version the debugger task can be invoked on each processor In addition as you are using a priority based scheduler the timing behavior might change Remember that with the single processor version you loose the prioritizing capability of the routing system Hence the programmer him self must ensure that the link communication does not jeopardize the real time performance When you keep these guidelines in mind using the single processor version of Virtuoso on multiple processors should be not much of a problem 16 4 Hints on system configuration Although Virtuoso permits you to place tasks semaphores mailboxes and queues on any processor you w
355. ivers will provide one or more subroutines that can be called from the task level and that implement the actual functionality of the driver At some point these functions will call KS_EventW or KS_ Wait to make the calling task wait for the completion of the driver action 3 One or more interrupt handlers are required to generate the events or sig nals waited for by these subroutines In the simplest case the only actions required from the ISR will be to service the hardware and to reschedule a waiting task and all data handling and protocol implementation can be done at the task level This method can be used if the interrupt frequency is not too high lt 1000HZ For higher data rates some of the task code should be moved to the ISR in order to reduce the number of task swaps In most cases the actions required from the interrupt handler will not be the same for each interrupt and some form of state machine will have to be implemented into the ISR If the number of possible states grows it is often much easier to use one or more PRHI processes to implement the protocol Processes can wait for interrupts at any number of places in their code and each of these points represents a state of the system As an example the Virtuoso network driv ers have been designed using this method The microkernel provides the DRIVER_REQ and DRIVER_ACK services to interface tasks to drivers based on PRHI processes At the time of writing th
356. ized in such a way that a simple modification of the makefile is all you need to build a system with or without debugger Note that on older versions of Virtuoso v 3 0 a slightly different mechanism Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 155 Debugging environment under Virtuoso was used This used a semaphore instead of a queue to start up the debug ger Refer to the examples or the read me files 15 2 4 Debugger commands Entering a response of H or h followed by a carriage return to the TLDE BUG prompt causes the debugger command menu to be displayed It appears as VIRTUOSO TL Debugger 3 09 NODE 1 NODE Started by user interrupt Allocation of memory Clock amp Timers Stack use Monitor listing Mailboxes Network info Other node Queues Resources Semaphores Task status Exit debugger Reset Counts Task Manager Mode NON KX HYDWD OO BZ KAR AQ BP This help screen 15 2 5 Tasks Selection of this option produces a snapshot of the state of all the tasks in the system as shown below The snapshot contains three columns of infor mation Name the task s symbolic name Prio the current task priority State current task state P2 156 Virtuoso Reference Manual Copyright 1996 Eonic Systems Debugging environment under Virtuoso
357. jects referencing to it will not be mapped over more than one target processor When common memory is used the objects must be protected using a resource lock InputQueue J ConsolelnputDriver D OutputQueue ConsoleOutputDryiver Display Task Node 4 SamplingTas Node 3 Microkernel Object Processor Node FIGURE 1 A possible mapping of objects onto a network P1 12 Virtuoso User Manual Copyright 1996 Eonic Systems Virtuoso an overview 3 3 A multi level approach for speed and flexibility As any designer knows a single tool or method cannot cover all of the differ ent aspects of an application In particular DSPs are increasingly used for signal processing and embedded control at the same time This poses quite a challenge to the programming tool as it must handle timing constraints expressed in microseconds Traditionally this meant programming in assem bler at the interrupt level One of the drawbacks of this approach is a lack of modularity and hence the sheer impossibility to build complex multitasking applications Real time multitasking kernels on the other hand provide for modularity but impose an unacceptable overhead for handling fast interrupts at the task level On parallel DSPs the situation is even more demanding than on single pro cessor DSPs The reason is that interprocessor communication is generat ing interrupts that have to be processed at the system level
358. k is made runable and its entry point is called If the task is of higher priority than the current task a context switch is performed and the new task runs otherwise control is returned to the caller NONE K_TASK SHUTDOWN KS_Start SHUTDOWN start SHUTDOWN KS_ Abort This is NOT arecommended way to start a task at short notice or to perform a programmed task switch A much faster way to start execution of a task is to start it before it is actually needed and make it wait on a semaphore or use a KS_Suspend KS_ Resume pair If this service is used in an attempt to restart a task that is already running the result is unpredictable but almost certainly not what was wanted P2 98 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services 11 61 e SUMMARY e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES KS StartG Start a group of tasks Task void KS_StartG K_TGROUP group The KS_StartG microkernel service is used to start a group or a number of groups of tasks This is much more efficient than starting each task individu ally as at most one task switch will be needed Its use also guarantees that on each node marking the tasks READY is an atomic operation NONE K_TGROUP WORKERS K_TGROUP SLAVES KS_StartG WORKERS SLAVES KS_ Abort If this service
359. k swaps In most cases the actions required from the interrupt handler will not be the same for each interrupt and some form of state machine will have to be implemented into the ISR If the number of possible states grows it is often much easier to use one or more PRHl processes to implement the protocol Processes can wait for Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 2 35 Predefined drivers 23 1 1 interrupts at any number of places in their code and each of these points represents a state of the system As an example the Virtuoso network driver have been designed using this method A number of device drivers are provided with this release of Virtuoso Clas sico VSP for SHARC a the timer device driver a two host interface device drivers a unidirectional DMA based link drivers both for internal and external memory a a bidirectional link driver internal memory only a aunidirectional core based link driver a aunidirectional DMA based RawLink driver The timer device driver void timer_drv int timer_prio Because of the possibility to use 2 different priorities for the timer IRQ a parameter had to be added to the driver The possible values of timer_prio are TMZLI indicating a low timer priority or TMZHI indicating the high timer priority The timer device driver is needed for time out features of some kernel ser vices and for kernel timer services The two procedures to read out t
360. l e EXIT CONDITIONS e DESCRIPTION EXAMPLE SEEALSO e SPECIAL NOTES Conditions upon return of the call A description of what the Virtuoso nanokernel service does when invoked and how a desired behavior can be obtained One or more typical Virtuoso nanokernel service uses List of related Virtuoso nanokernel services that could be examined in con junction with the current Virtuoso nanokernel service Specific notes and technical comments ADI 30 Virtuoso Binding Manual Copyright 1996 Eonic Systems Alphabetical List of nanokernel entry points 19 1 e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES _init_process Initialize a nanokernel process Process management void _init_process void stack int stacksize void entry void int i1 int i2 This C function initializes the process control structure of a process It must be called before the process is started using start_process The entry point the stacksize the initial values for i1 and i2 and some internal vari ables are written to the PCS none In this example two processes using the same code but different parameters are initialized and started int adc1 100 stack for first process int adc2 100 stack for second process extern void adc_proc void process code extern struct adc_pars ADC_Params 2 parameter structs
361. l K_ARGS A e DESCRIPTION This C callable function is used by all KS_ services to send command packets to the microkernel process e RETURN VALUE none EXAMPLE SEEALSO PRLO_PSH e SPECIAL NOTES This function must be called by microkernel tasks only Copyright 1996 Eonic Systems Virtuoso Binding Manual TI2 29 Alphabetical List of nanokernel entry points 38 6 e BRIEF scape Sas e GLASS ee eos ee SYNOPSYS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES KS_DisablelSR Remove an ISR from the interrupt vector table Interrupt service management void KS_DisablelSR int isrnum This C function is equivalent to KS_EnablelSR isrnum NULL The interrupt is disabled and the corresponding entry in the interrupt vector table is cleared none KS_DisableISR 34 remove the IIOF2 handler KS _EnablelSR SYSVEC Interrupt numbers are 0 31 for interrupts enabled in the IIE register m 32 35 for IIOFO IIOF3 TI2 30 Virtuoso Binding Manual Copyright 1996 Eonic Systems Alphabetical List of nanokernel entry points 38 7 SYNOPSYS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES KS EnablelSR Install an ISR and enable the corresponding interrupt Interrupt service management void KS_EnablelSR int isrnum void isr void This C function is used to
362. l data structures cccghi5sietscatthacesnieaatliddiviceseetiinaendeed sesamiae ADI 8 Process MANAQEMONLS 2c wesstosietaeacseasneceeteliieenh teere eid ai aE aaa Eran aa ADI 9 Nanokernel COMMUNICATIONS c cccceeeeeceeeeeeeeeeeeeeeeeeeenee seeeeeeeeeeneeneneneee ADI 11 SEMA_CHAN counting or semaphore Channel cceceeeeeeeeeeeeeene anes ADI 11 LIFO_CHAN List channel ccccccccccceececeeeceeeeeesesceeeseee eeesesseeeseeseeae eae ADI 11 STACK_CHAN Stack Channel cccccccccccceccsseececeecceceeeescaeeeseesseseseeeeseas ADI 12 Register conventions 22 5 gcse ak dak cticssed fhe ceases es ete aaienedasats seaedestvaca osteaeecnceutns ADI 12 Interrupt handling szscecsecesseiciceetsatlande ade edeastaus idneisevadeloratintaeet intend are ADI 14 The ISH SIG VGN creire eee ee gee eaa Ee a eed ee aes eee ADI 15 Communicating with the microkernel ccccceceeeeee ceeeeeeeeeeeeeeneeaeeeenaeeeees ADI 15 Additional microkernel features On the 21060 cececeeceeeceeeeeeeeeeeeeeeeeeeeteee anes ADI 18 Use of the PC stack and the Counter stack eccceeceeeeeeeeceeeeneeeaeeeeneeaees ADI 18 Extended Context zerien na e adit diamines eat nanan ADI 18 Copyright 1996 Eonic Systems Virtuoso User Manual TOC 9 Alphabetical List of nanokernel entry points ADI 19 Slarl PrOC SS iite hehe th E E eae Naed aelaviian cha ADI 20 ENDISRai ccetiages cv aa a hive lave is eee ee
363. l in the main routine An example Wrong allocate a global object and call its constructor Constructor calls some kernel services based on the parameters passed MyClass aGlobalObject paraml param2 param3 int main netload kernel_init if K_ThisNode 0x00010000 KS_StartG EXE_GROUP kernel_idle return 0 Correct allocate a global object and call its default constructor Default constructor calls no kernel services MyClass aGlobalObject int main netload kernel_init Explicitly call initialsation function that will call some kernel services based on the parameters passed aGlobalObject Init paraml param2 param3 if K_ThisNode 0x00010000 KS_StartG EXE_GROUP kernel_idle return 0 P2 198 Virtuoso Reference Manual Copyright 1996 Eonic Systems Virtuoso The Virtual Single Processor Programming System Covers Virtuoso Classico Virtuoso Micro Version 3 11 Part 3 Binding Manual Copyright 1996 Eonic Systems Virtuoso Binding Manual P3 P3 2 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Analog Devices 21020 DSP 18 Virtuoso on the Analog Devices 21020 DSP 18 1 Virtuoso implementations on the 21020 At this moment both VIRTUOSO MICRO as VIRTUOSO CLASSICO exists for the ADSP 21020 These implementations contain the microkernel a
364. l packets sent or received through the network are allocated from the K_ArgsFree list they should be deallocated after use The network transmitters always free a packet after it has been sent The microkernel deallocates a packet if the Scre field is not zero Consequently command packets not allocated from the free list must have their Scre field set to zero to prevent deallocation Note we are aware of the fact that this logic is a bit confusing Future ver sions of the microkernel will probably use a separate flag to indicate if a packet was dynamically allocated Interrupt handlers and PRHI processes can request a microkernel service by building a command packet and pushing a pointer to it on the microkernel input channel The only services that can be safely called are the equiva lents of KS_Signal and KS_SignalM Also note that using events will be faster than signalling The code fragments below show how to perform a KS_Signal or KS_SignalM call from within the ISR In this example the command packet is created and initialized in C but the same thing could be done entirely in assembly language The function install_my_isr is called to initialize the command packet and install the ISR K_ARGS CP1 CP1P K_SEMA SLIST1 SEMA1 SEMA2 ENDLIST extern void my_isr void void install_my_isr ADI 2 16 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the ADSP 2106x SHARC
365. l service is equivalent to calling KS_Suspend for every task that is a member of the specified group s The service is per formed atomically on each node NONE K_TGROUP CONTROL KS_SuspendG CONTROL suspend all tasks in CONTROL group KS_ Suspend KS_ Resume KS_ResumeG Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 103 Alphabetical List of Virtuoso microkernel services 11 66 e SUMMARY e CLASS ey eae e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES KS _ Taskid Read task identifier Task K_TASK KS_TaskId The KS_Taskld microkernel variable contains the calling task s identifier NONE printf Hi I am task 08x n KS_TaskId j KS_TaskPrio KS _Nodeld This variable should be treated as read only This may be enforced by future versions of the microkernel or the variable may be replaced by a function P2 104 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services 11 67 e SUMMARY e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES KS _TaskPrio Read current task priority Task int KS_TaskPrio The KS_TaskPrio microkernel variable contains the calling task s current pri ority NONE K_MBOX BOX1 K_MSG msg KS_SendW BOX1 KS_TaskPrio amp msg Send at curre
366. l topology transparency and offers the highest degree of flexibility The overhead at this level comes not as much from the use of C and the heavier register context but mainly from the heavier semantically context offered by the microkernel services Good programming practice dictates a concern for portability and scalability of the application Hence one should program as much as possible at the microkernel level Programming at the lower levels can be justified for two reasons 1 Faster response times 2 Better performance Indeed the lowest levels will always preempt the higher levels and because of the minimum context have a lower overhead However these levels are processor dependent dictated by the use of assembly and should only be used when needed as portability and scalability are lost Copyright 1996 Eonic Systems Virtuoso User Manual P1 15 Virtuoso an overview Most real time kernels only provide a single ISR level and the C task level as this is sufficient for supporting applications using standard microprocessors and microcontrollers This is also the case for ports of Virtuoso to this class of processors 3 4 An execution trace illustrated T 2 TaSk Prio1 ask PTio Task Prio3 Task Prio4 IdeTasiii LiteTask1 LiteTask2 iteTas Micro Kerne
367. lds relocatables for a version with the debugger Each makefile will build a library from the relocatables The list of relocat ables is found in files relocs Ist for the version without debugger and rels dbg lst for the version with debugger At the present time the libraries Copyright 1996 Eonic Systems Virtuoso Binding Manual M2 1 Virtuoso on the Motorola 68030 systems 28 2 cannot be used yet to build executable applications since the order of the relocatables in the libraries is not yet optimal The makefiles presume following directory structure n0 IRTUOSO EES SSSSSS 55 RELS_NODBG The source files and makefiles reside in subdirectory GNU C Relocatables compiled without debugger option go into subdirectory RELS_NODBG those compiled with debugger option go into subdirectory RELS Building an application executable Two demos on the disk can serve as a guide to build an application Each of the demos can be built with or without the task level debugger incorporated The makefiles of these demos presume the following directory structure n0 VIRTUOSO TEST TEST_SIO RELS RELS_NODBG RELS RELS_NODBG Following source files must be present in the source directories TEST and TEST_SIO C files demo c drivl c nodel c h files dllist h iface h k_struct h k_types h nodel h siotags h tstdio h makefiles m
368. led An interrupt of higher priority can interrupt an interrupt of lower priority An interrupt ends with a call to the nanokernel function ENDISR1 At that point the nanokernel will verify if a process swap is required and allowed The condition tested is the logical AND of a NANOK_PRHI 0 The current process is a PRLO process a NANOK_HEAD 0 There is a PRHI process a NANOK_CRIT 0 There are no more nested interrupts In case of a swap the interrupt is finished and the PRHI process is swapped in If there are nested interrupts first all interrupts are finished NOTE As NANOK_CRIT is not used in the nanokernel on 21060 the last test has been replaced by a check of IMASKP 21 7 11 Communicating with the microkernel As mentioned before the VIRTUOSO microkernel is implemented as a PRHI process It uses a single stack based channel to receive commands from the tasks the network drivers other PRHI processes and interrupt han dlers A pointer to this channel is exported in the C variable K_ArgsP Two types of data can be pushed onto this channel 1 Small integers 0 63 are interpreted as events Events are simple binary signals that a task can wait for using the KS_EventW service Most events will be generated by interrupt handlers and driver processes For the 21060 version event numbers have been assigned as follows m 8 host event 10 15 event numbers for KS_LinkOutW 16 21 event numbers for
369. lished by the following call in main1 c KS_StartG EXE_GROUP In main1 cpp the C object encapsulating to the EXE task group is used to start all the tasks in the EXE group ExeTaskgroup Start In test1 cpp we find similar extern C constructs as in main1 cpp We also discover extensive use of the C objects to perform the benchmarking tests of the D1P sample These changes are highlighted in the file listing given below It is clear from this modified sample that the use of the C interface to Virtu oso allows a more object centered way of writing the code It is also possible to write simplified code with less pointers or address of operators All the mailbox operations that send or receive a message in the test1 cpp file can actually pass a KMessage object as an argument instead of a pointer to a K_MSG structure This implies that one can simply write Message as a parameter instead of amp Message which improves code readability P2 192 Virtuoso Reference Manual Copyright 1996 Eonic Systems Microkernel C interface testl cpp extern includ includ includ include include include extern extern extern extern extern static static static define FORMAT void message_test moan e lt string h gt e lt _stdio h gt e iface h e nodel h vkobjcts hpp vkobl hpp vkmsg hpp wou wo wou wou won
370. lmost a religious issue Many low level features you need to know on traditional processors are not needed on the transputer because they are solved in hardware but the drawback is that one only has FIFO based scheduling 33 2 The transputer an example component for distributed processing When INMOS launched the transputer on the market the goal of it was manyfold but primarily to provide cost effective parallel processing A sec ond but certainly as important aspect was the software methodology behind the transputer People at INMOS were aware of the immense problems posed by large sequential programs as they are used for more and more complex systems especially as for reasons of performance more than one processor is needed Therefore the software concept was developed first and the transputer afterwards The idea was simple in order to manage complexity one has to divide the whole up in smaller manageable components with well defined interfaces They derived this idea from the so called CSP computing paradigm CSP stands for Communicating Sequential Processes and describes programs as consisting of a number of processes that interact exclusively through com munication The point is that a lot of the problems programmers need to solve by writing a computer program reflect this paradigm very well Exam ples range from a dataprocessing application pipelined transformation of generated data to finite element programs where each subs
371. ly save to start up new threads although no tasks should be started up in the transputer high priority queue c LSC channel I OChannel I O to threads which are not generated from the same master task ChanOutTimeFail ChanInTimeFail ChanAlloc ChannelFree For external links use KS_LinkinW and KS_LinkoutW For reading the event pin use KS_EventW For intertask communication you can use mes sage calls malloc calloc realloc free T8 14 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the INMOS T2xx T4xx T8xx d LSC semaphore functions Semaphore functions within threads which are not generated from the same master task SemAlloc SemFree For intertask synchronization you can use the Virtuoso semaphore functions Note the differences between the types e All standard file I O routines like printf scanf etc Use the supplied I O library functions instead Copyright 1996 Eonic Systems Virtuoso Binding Manual T8 15 Virtuoso on the INMOS T2xx T4xx T8xx T8 16 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the INMOS T9000 transputer 34 Virtuoso on the INMOS T9000 transputer In the mean time the T9000 the transputer of the second generation is com ing to the market announced end of 1992 It features a tenfold increase in performance in computing and in communication performance as compared t
372. malist a test if a semaphore was signalled int KS_Test K_SEMA sema Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 13 Virtuoso microkernel services m wait for a semaphore int KS_TestW K_SE int KS_Wait K_SE T m wait for a semaphore int KS_TestWT K_S K_T int KS_WaitT K_S K_TI Gl m wait for one of many K_SEMA KS_TestMW K_SEMA KS_WaitM K_S to be signalled MA sema A sema with timeout EMA sema ICKS ticks A sema CKS ticks semaphores K_SEMA semalist GJ A semalist m test for one of many semaphores and wait with timeout K_SEMA KS_TestMWT K_SEMA KS_WaitMT K_SEMA semalist K_TICKS ticks K_S K_TICKS ticks CJ A semalist m return the current semaphore count int KS_InqSema K_SEMA sema m reset a semaphore count to zero void KS_ResetSema K_SEMA sema m reset multiple semaphores void KS_ResetSema m insert message into a M K_SEMA semalist 8 5 Mailbox microkernel services mailbox int KS_Send K_MBOX mailbox K_PRI O prio K_MSG msgstruc m insert message into mailbox and wait till done int KS_SendW K_MBOX mailbox K_PRIO prio K_MS G msgstruc P2 14 Virtuoso Reference Manual Copyright 1996 Eonic Systems Virtuoso microkernel services m insert message into mailbox and wait with timeout int KS_SendWT K_MBOX mailbox K_PRIO prio
373. ments TMS320C40 36 2 Programming in C and assembly This section introduces some implementation defined features of the Texas Instruments C compiler system Please refer to the Compiler and Assembly Tools Manuals for full details 36 2 1 Data representation All integer based types including characters are represented as 32 bit words This has the unusual consequence that sizeof char sizeof short sizeof long 1 All floating point types are represented using an internal format with an 8 bit exponent and a 24 bit mantissa A floating point value stored in a register has a 32 bit mantissa but this will be truncated when stored to memory The full 40 bits can be read or written using assembly language but this requires two memory words for each value All pointer types are represented as a 32 bit memory address The C40 has two external memory interfaces and a large number of internal buses but they all use a separate address space As a consequence every data item in memory can be referenced by a unique pointer 36 2 2 Big and Small Models The compiler supports two memory models The only difference between these is in the way static data are accessed With the small model the DP data page pointer register is only initialized once All static data references are made using single instructions assuming the value of DP is valid The means that the bss section cannot span any 64K address boundaries With the big
374. mmunication ports each offering up to 20 MBytes s and two memory interface ports 100 MB s providing a total peak bandwidth of up to 320 MB s As the links are 8 bit parallel and run at 20 MHz they provide for a very high bandwidth The communication ports can also directly be interfaced to peripheral devices Internally there is a six channel DMA coprocessor that permits to execute memory operations while the CPU is handling computational tasks The CPU is upwards binary compatible with the CPU of the TMS320C30 It contains a single cycle floating point and integer multiplier and permits the parallel execution of instructions Most instructions are single cycle The floating point operations operate on 40bit floating point numbers Copyright 1996 Eonic Systems Virtuoso Binding Manual Tl2 1 Virtuoso on the Texas Instruments TMS320C40 36 1 1 TMS320C40 Chip Architecture Cache RAM BlockO RAM Block1 ROM Block 128 words 4K Bytes 4K Bytes Reserved Local Global Memory 2 Program and Data Buses Memory Port 3 Program and Data Address Buses Port 2 GByte 1 DMA Address Bus 2 GByte 2 32bit CPU busses lg 2 40bit register busses 1 DMA Data Bus 6 channels DMA Coprocessor 1 Peripheral Data Bus 1 Peripheral Address Bus A Y Multiplier 32bit Barrel Shifter ALU Address amp Disp Registers 40bit registers RO R1
375. must then be reset and the server program must reload and restart the application from the beginning The timer interrupt routine has a special feature built in for visual inspection of its healthiness Somewhere in the code of the timer interrupt routine a subroutine jump is done to a routine called heartbeat This routine changes a LED in the front of the processor board each half second If this feature is not desired the BSR instruction to the heartbeat routine is to be put in comment kernel a This is the very core of the Virtuoso kernel All interrupt routines at this moment only the mailbox and the timer interrupt routine and Virtuoso ker nel service requests enter this module The kernel service requests are translated to a processor TRAP so that all kernel services are processed in the supervisory state of the processor together with the interrupt process ing The kernel initialization routine also contains initialization of the cache con Copyright 1996 Eonic Systems Virtuoso Binding Manual M2 7 Virtuoso on the Motorola 68030 systems trol register of the processor This will only go for the 68030 processor type If cache operation is not desired two instructions within the kernel initializa tion routine must be put in comment move l 3919 d0 movec d0Q CACR The last instruction of the kernel initialization routine transfers the processor state to User Mode This instruction must always be the
376. n the number of 8 bit bytes in a type P2 58 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services 11 29 e SUMMARY e CLASS Saw es e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES KS_LinkinWT Read a datablock from a link with timed out wait Processor specific int KS_LinkinWT int link int size void datablock K_TICKS ticks This call reads data from a processor link The call returns when the dat ablock has been read in or when the timeout has expired Meanwhile the calling task is put in a LinkWait State RC_OK if reading is finished before the timeout expires RC_TIME other wise char buf 128 int RetCode read 15 bytes from link 3 store it in buf don t wait more than 1000 ticks Ay RetCode KS_LinkinWT 3 15 buf 1000 if RetCode RC_OK printf timed out reading data n KS _Linkin KS_LinkinW KS_Linkout KS_linkoutW KS_LInkoutWT iface h This service is only implemented on transputers Reading from a link without Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 59 Alphabetical List of Virtuoso microkernel services using this service will have unpredictable side effects The size parameter is the number of 8 bit bytes to be read Care needs to be taken when specifying the size parameter on systems where characters are stor
377. n ISR a Interrupts that must be disabled at certain sections in the ISR code Saving or preserving registers There are two sorts of ISRs that can be written 1 ISRs that stand on their own and do not make use of the kernel to give signals 2 ISRs giving signals to the kernel In both cases the Stack Pointer R7 must first be incremented prior to sav ing any register at the start of an ISR This is because a critical section exists in the epilogue code of a procedure move R7 move y R7 lt reg gt This instruction sequence restores a previously saved register If an interrupt occurs in between these two instructions the Stack Pointer points to the address where the value of the preserved register is written and the first move in the ISR to save a register will overwrite that value if no prior incre ment of R7 is done The same goes for the preservation of SSH Keeping this potential danger in mind the following prologue code must be used for an ISR of the first class no kernel interaction move R7 prior increment of the SP move lt reg gt y R7 repeat this instruction for every register that must be saved At the end of the ISR right before the RTI instruction following epilogue Copyright 1996 Eonic Systems Virtuoso Binding Manual M3 15 Virtuoso on the Motorola 96K DSP code must be used move R7 move y R7 lt reg gt repeat this instruction for every re
378. n an appropriate way Overhead is reduced by a factor of 10 when compared to similar microkernel operations In Virtuoso Nano solely based on the nanokernel some of these restrictions were lifted Refer to the product manual The rest of this chapter is specific for the nanokernel as used within Virtuoso Classico 9 2 Nanokernel channels Nanokernel processes can synchronize using three types of channels 1 Acounting semaphore channel 2 Alinked list channel 3 Astack channel Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 21 Nanokernel types and datastructures More details are available in part 3 for each processor type P2 22 Virtuoso Reference Manual Copyright 1996 Eonic Systems Nanokernel services 10 Nanokernel services 10 1 The nanokernel processes have a much simpler scheduling mechanism and set of services than the microkernel tasks Nanokernel processes are never preempted by another nanokernel process and hence are by definition critical sections Nanokernel processes only deschedule voluntarily upon issuing a kernel service They execute in pure FIFO order when executable Note however that they can be interrupted by an ISR level routine but will themselves preempt any microkernel task when becoming executable Hence consider the nanokernel level as a set of high priority processes while the microkernel tasks have a low priority Note that the microkernel itself is a nanokernel proces
379. n application that is built to run on OS 9 cfr the module cstart r Initialization of the data area uninitialized as well as initialized must now be done by the application itself OS 9 isn t there anymore to do this job This module will calculate and fill in the global data pointer in register a6 of the Copyright 1996 Eonic Systems Virtuoso Binding Manual M2 5 Virtuoso on the Motorola 68030 systems processor When an application is built to run on a non OS 9 target system the block of initialized data will follow immediately after the object code of the application gt increasing address gt size of Sige of San initialized application code un initialized initialized data data block data block block Ss 1 longword 1 longword To find the block of initialized data the starter routine will search for the first initialized data value This is a value defined in this module the hex value FEEDCODE This is another reason why this module must be linked first in the executable Once this value is found its address is used as the global data pointer and filled in register a6 The data block of the initialized data however is not yet at the right place The application expects that the global data pointer in register a6 will point to the first byte of the un initialized data block The ordering of the data blocks expected by
380. n of all sources this would be neces sary if SYSDEF is modified CLCKFREQ this should be defined to be the clock frequency of the hard ware timer used to generate the TICKS time TICKTIME the TICK period in microseconds TICKUNIT the TICK period in CLCKFREQ units TICKFREQ the TICK frequency in Hertz The number of available timers command packets and data packets are also defined in this file How much you need of each depends on your appli cation but the following guidelines may be followed Timers are used to implement time outs and can also be allocated by a task A command packet will be needed for each timer allocated by a task Com mand packets used for calling a kernel service are created on the caller s stack and should not be predefined MAIN1 C also defines some variables used by the console driver tasks the clock system the debugger task and the graphics system These are included automatically if you use the standard names for the required kernel ADI 2 42 Virtuoso Binding Manual Copyright 1996 Eonic Systems Application development hints objects XXX ACH specifies architecture file MAKEFILE The makefiles supplied in the EXAMPLES directory can easily be modified for your application They also show how to organize things so you can optionally include the task level debugger If you want to include the task level debugger put the corresponding definitions out of comment VIRTLIB
381. n request a microkernel service by building a command packet and pushing a pointer to it on the microkernel input channel The only services that can be safely called are the equivalents of KS_Signal and KS_SignalM and the DRIVER_ACK service Also note that using events will be faster than signals The code fragments below show how to perform a KS_Signal or KS_SignalM call from within an ISR In this example the command packet is created and initialized in C but the same thing could be done entirely in assembly language The function install_my_isr is called to initialize the command packet and install the ISR K_ARGS CP1 CP1P command packet for use by my_isr K_SEMA SLIST1 SEMAl1 SEMA2 SEMA3 ENDLIST extern void my_isr void void install_my_isr Copyright 1996 Eonic Systems Virtuoso Binding Manual TI2 19 Programming the nanokernel create a pointer to the command packet CP1P amp CPl initialize CP1 for a KS_Signal SEMA1 service CP1 Srce 0 CP1 Comm SIGNALS CP1 Args sl sema SEMAI1 or for a KS_SignalM SLIST1 service CP1 Srce 0 CP1 Comm SIGNALM CPl Args sl list SLIST1 install the ISR KS_EnableISR my_isr For the ISR something like the code listed below will be required ref _CP1P ref _K_ArgsP def _my_isr _my_isr lat PRHI_PSH Signal semaphore s ldi _K_Args
382. n the function return address When this register is used later on it must be placed on the stack on function entry The compiler makes also some assumptions about how functions treat regis ters There are two classes of registers Compiler registers these registers are preserved across function Calls Scratch registers these registers are not preserved across function calls See User s Manual for detailled list Registers may be saved by pushing them on the stack You can use the fol lowing instruction dm i7 m7 r3 places r3 onto the stack and decrements the pointer a r3 dm 1 i7 reads the stack The stackpointer is not incremented modify i7 1 increments the stack In the C environment arguments are passed to functions by placing them in registers or on the stack according to following rules 1 At most three arguments are passed in registers R4 R8 R12 2 Once one argument has been passed on the stack all remaining arguments are on the stack 3 All values wider than 32 bits are passed on the stack The return value of the function must be placed in the appropriate registers If a single word is being returned it must be returned in register RO If a two ADI 12 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Analog Devices 21020 DSP word value is being returned it must be returned in registers RO and R1 The calling protocol in a C environment involves sev
383. nal memory are handled in 2 steps First data is trans ferred to from internal memory using DMA In the second step the data is transferred to from internal from to external memory also using DMA The arguments m link_no buffer_no link buffer you wish to use m direction RX for receive TX for transmit m speed SSPEED for single speed DSPEED for double speed 4 void NetLinkDMAExtC int link_no int buffer_no int direction int speed This is the unidirectional DMA driver for the link ports This driver can be used for transfers from or to the internal and external SHARC memory The transfers to external memory are handled in 2 steps First data is trans ferred to from internal memory using DMA In the second step the data is transferred to from internal from to external memory This last step is a core transfer The arguments m link_no buffer_no link buffer you wish to use mw direction RX for receive TX for transmit speed SSPEED for single speed DSPEED for double speed 5 void NetLinkDMA2 int link_no int buffer_no int token int speed This is the bidirectional driver for the link ports You may experience prob lems with this drivers if you are using pre rev 2 0 silicon The arguments m link_no buffer_no link buffer you wish to use a token initial location of the token Token exchange is performed auto matically but the driver needs the initial position Values TOKEN NOTOKEN AD
384. nclude macro h extern K ArgsP microkernel input stack send a command packet to the microkernel assume i0 points to the command packet i4 dm _K_ArgsP r2 dm 0 i0 PRHI_PSH SEEALSO PRHI_POP PRHI_LPOPW e SPECIAL NOTES This entry point must not by called from the low priority context but it can be used by interrupt handlers ADI 2 30 Virtuoso Binding Manual Copyright 1996 Eonic Systems Alphabetical List of nanokernel entry points 22 12 PRHI_SIG BRIEF Send an event on a signal channel CLASS Process communication e SYNOPSIS PRHI_SIG PRHI SIG is defined in macro h e DESCRIPTION If a process is waiting for the channel it is rescheduled put at the tail of the process FIFO Otherwise the event count is incremented In either case control returns to the caller e ENTRY CONDITIONS i4 pointer to channel e EXIT CONDITIONS rO r1 r2 i4 ASTAT are corrupted All other registers are preserved EXAMPLE include macro h i4 dm SYNC_CHAN PRHL SIG SEEALSO PRHI WAIT e SPECIAL NOTES This entry point must not by called from the low priority context but it can be used by interrupt handlers Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 2 31 Alphabetical List of nanokernel entry points 22 13 PRHI WAIT e BRIEF Consume an event from a signal channel or deschedule CLASS Process communica
385. nclusion is clear the only way to shorten the development cycle is to use tools that relieve the developer from the technology change The ideal development tool must not only provide for faster application development by giving the programmer a head start but should also be future proof The requirements can be split in three areas 1 Aconsistent high level API across all target processors 2 The utilities to debug and maintain the code 3 Target processor specific support for best performance The high level view a portable set of services A multi tasking real time microkernel as the essential module In many applications sensors supply raw data preprocessing algorithms fil ter and examine the data control algorithms process the data and deduce from it control commands while additional functions deal with user interac tion data logging or safety concerns In most cases tight timing require ments need to be fulfilled especially if the system has to deal with events that can happen at any time regardless of the current function being executed at that moment A common and proven solution is to map the different functions onto separate tasks assign priorities to these tasks and to use a standard ized way of defining the interaction between the tasks The core of this solu tion is the availability of a real time microkernel that manages the timely execution of the tasks and their interactions in a way that frees the applica tions pr
386. nd the nanokernel and are dedicated to single processor and multiprocessor systems Until now the implementation of VIRTUOSO CLASSICO for multi processor systems is restricted to communication by shared memory 18 2 DSP 21020 chip architecture This section contains a brief description of the ADSP 21020 processor archi tecture It is not intended to be a replacement of the Processor s User Man ual but as a quick lookup for the application programmer Detailed information can be found in the ADSP 21020 User s Manual from Analog Devices Inc The ADSP 21020 is the first processor in the Analog Devices ADSP 21000 family of floating point digital signal processors The technological founda tion for the ADSP 21020 is the powerful Harvard architecture The processor has two distinct but similar memory interfaces one for program memory which contains both instructions and data and one for data memory which contains data only Each address space on the ADSP 21020 can be divided into banks for selection The program memory address space is divided into two banks The data memory is divided into four banks See also chapter about the architecture file The computation units of the ADSP 21020 provide the numeric processing power for performing numerically operations The 21020 contains three com putation units a an arithmetic logic unit ALU a multiplier m a shifter The computation units are arranged architecturally in par
387. nderstanding of how the nanokernel operates A process is represented by a pointer to a Process Control Structure PCS For PRHI processes the PCS occupies the first eight words of its stack A static PCS is used for the IDLE process The first word of a PCS is a pointer to another PCS or NULL This is used to build linked lists of processes More details of the PCS will be introduced in the section on process man agement A channel is represented by a pointer to a Channel Data Structure CDS The first word of a CDS is a pointer to the PCS of a process waiting on that channel or NULL Other fields depend on the type of the channel and will be introduced in the section on nanokernel communications The following static variables are used by the nanokernel to keep track of the state of the system NANOK_PRHI Pointer to the PCS of the current PRHI process or NULL if there is none NANOK_HEAD NANOK_TAIL Head and tail pointers for a linked list of PRHI processes that are ready to run When a process becomes ready to execute it is added to the tail of the list When the current PRHI process is swapped out the process at the head of the list is removed and becomes the current process If the list is empty the PRLO process is swapped in NANOK_PRLO Pointer to the PCS of the PRLO process This is a constant as far as the nanokernel is concerned The microkernel modifies this pointer behind the scenes Copyright 199
388. nding Manual T1l2 7 Programming the nanokernel 37 Programming the nanokernel 37 1 Introduction The nanokernel provides the lowest level of functionality in the Virtuoso sys tem It is designed to perform extremely fast communication and context swapping for a number of processes It also provides the entry points neces sary to integrate interrupt handlers with the rest of the system The price to pay for speed is that nanokernel processes and interrupt handlers must observe very strict rules regarding their use of CPU registers and the way they interact with each other From the point of view of the nanokernel an application program consists of a collection of three types code modules asingle low priority PRLO process any number of high priority PRHI processes any number of interrupt handlers It is important to understand what exactly is meant by a process A process is a thread of execution that has both an identity and a private workspace These two properties which are logically equivalent make it possible for a process to be swapped out and wait for an external event while another pro cess is allowed to continue Interrupt handlers in contrast do not have a pri vate workspace The PRHI processes are scheduled in strict FIFO order and must observe the special register conventions mentioned above The PRLO process is assumed to be a C function using the compiler register conventions and mu
389. nding task will wait until a receiver is ready to accept the message RC_OK K_MSG msg K_TASK LOWTASK K_MBOX POBOX9 char datastring testdata msg task LOWTASK msg size strlen datastring 1 msg data datastring void KS_SendW POBOX9 3 amp msg printf Message transmitted and received n KS_Send KS SendWT KS _ Receive KS _ ReceiveW KS _ReceiveWT The size member is the number of 8 bit bytes in the message Care needs to be taken when specifying sizes on systems where characters are stored one per word or where sizeof does not return the number of 8 bit bytes in a type P2 88 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services 11 52 e SUMMARY e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO KS_SendWT Send a message with timed out wait Mailbox int KS_SendWwT K_MBOX box K_PRIO prio K_MSG msg K_TICKS ticks The KS_SendWT microkernel service is similar to the KS_SendW microker nel service described above except that the waiting time is limited to the number of ticks specified If the call times out no message is left in the mail box RC_OK if successful RC_TIME if timed out K_MSG msg K_MBOX BOX1 K_TASK RECEIVER char datastring testdata msg size strlen datastring 1 msg tx_data datastring msg rx_task RECEIVER
390. ng Manual ADI 39 Alphabetical List of nanokernel entry points 19 9 PRHI_POP e BRIEF Remove next element from a stack channel e CLASS Process communication e SYNOPSIS PRHI_POP PRHI_POP is defined in macro h e DESCRIPTION If the stack is not empty the top element is removed and returned to the caller The Z flag is reset If the stack is empty the Z flag is set and an unde fined value is returned The calling process is never swapped out as a result of calling this service e ENTRY CONDITIONS i4 pointer to stack channel struct e EXIT CONDITIONS If the stack is not empty r8 r0 rlare corrupted r2 th lement removed from the stack the Z flag is cleared If the stack is empty r8 r0 rl are corrupted r2 undefined the Z flag is set EXAMPLE include traps inc i4 dm CHANNEL PRHI_POP SEEALSO PRHI_POPW PRHI_PSH e SPECIAL NOTES This service must not be called from the low priority context ADI 40 Virtuoso Binding Manual Copyright 1996 Eonic Systems Alphabetical List of nanokernel entry points 19 10 BRIEF soe eee a e CLASS 2 Saw es e SYNOPSIS e DESCRIPTION e ENTRY CONDITIONS e EXIT CONDITIONS EXAMPLE SEEALSO e SPECIAL NOTES PRHI_POPW Remove next element from a stack channel or deschedule Process communication PRHI_POPW PRHI_POPW is defined in macro h If the stack
391. ng Point with CPU context on every task switch Real time sys tems typically have only a small number of the tasks in the entire suite of tasks which require floating point support Context switch time is minimized by performing the FPU context swap only on demand e example TASK TLDEBUG ROOT 1 tldebug 400 SYS EXE 14 5 Semaphore definitions e syntax SEMA lt name gt lt node gt ename The name of the semaphore according to the standard name convention node This is the network node the semaphore is placed on example SEMA ALARM P345 14 6 Resource definitions e syntax RES lt name gt lt node gt name Thename of the Resource according to the standard name convention node This is the network node that manages the access to the resource E g when the resource is the console the node is the one on which the drivers are placed for accessing the console example RES HOSTRES ROOT 14 7 Queue definitions e syntax QUEUE lt name gt lt node gt lt width gt lt depth gt name Thename of the Queue according to the standard name convention ewidth The width of the queue is defined as the number of words in a single entry P2 150 Virtuoso Reference Manual Copyright 1996 Eonic Systems System Configuration The number must be nonzero The depth field defines the number of entries in the queue The depth must be nonzero The m
392. ng a cyclic timer The net result is once again more complex programs The worst side effect however is that the problem is solved in an application dependent manner In addition this results in a high overhead See 12 13 for an example A general solution consists in using multiple priorities This was demon strated by various authors See 4 5 6 7 The use of multiple priorities and the use of an appropriate scheduling algorithm can guarantee under the right conditions the timely execution of all processes As such the determi nation of the priority of each process is application dependent On a single processor a rate monotonic scheduler where the priorities are inversely related to the periodicity of the processes will result in a feasible scheduling order if the workload is under 70 An algorithm that better deals with ape riodic events is the earliest deadline This can guarantee the scheduling of all processes even if the workload is close to 100 7 In general the prob lem in known to be NP complete especially if all factors such as aperiodic events and common resources are taken into account In these cases a pri ority inheritance mechanism is advisable 5 11 Fortunately the general case is often an exception so that most applications can be implemented using simpler algorithms Modifying the FIFO scheduler on the transputer For the processor dependent low level routines written in assembler two maj
393. nic Systems Virtuoso User Manual LIC 7 License agreement LIC 8 Virtuoso User Manual Copyright 1996 Eonic Systems Virtuoso w The Virtual Single Processor Programming System Covers Virtuoso Classico Virtuoso Micro Version 3 11 Part 1 The concepts Copyright 1996 Eonic Systems Virtuoso User Manual P1 Creation February 5 1990 Last Modification September 6th 1996 P1 2 Virtuoso User Manual Copyright 1996 Eonic Systems Installation 1 Installation 1 1 Installing the software The Virtuoso Package is available in two types of licenses The fist one only contains the binary files while the second one is delivered with the source code The source code is delivered on a separate floppy For the rest of this manual we will simply refer to Virtuoso To install the Virtuoso package on a PC hosted system follow this procedure 1 Insert the floppy in the drive 2 Type install Follow the instructions on the screen This will create the virtuoso directories on the requested drive and copy the files onto the hard disk If you want to install onto a different structures edit the install bat file but be aware that the supplied makefiles assumes a subdi rectory structure as the one on the floppies The installation on UNIX hosted systems is similar but uses a tar file Please read the readme file first before you proceed any further Next you will need to set up the pat
394. nkDma This describes the following network Net Link_ Driver E2 3 ma DE3 ma Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 147 System Configuration Server Host Interface p Netlink lt Rawlink 14 3 2 The routing tables On each processor the kernel uses a local routing table to know how to reach other processors This means that there is no master processor in the system Virtuoso uses a local routing schema Basically it is a table indexed by the P2 148 Virtuoso Reference Manual Copyright 1996 Eonic Systems System Configuration Processor Number where each entry presents the local driver that can be used to forward further the packet to the target node Parallel routes with the same minimal length are included Below is the routing table for NODES of the previous example The routing tables are part of the generated nodex c file and should not be modified by the user static int R0001 f static int R0002 static int R0003 0 1 5 Sal 4 1 int RouteInd R0001 R0002 NULL R0003 Obviously some ports are not part of the routing network It could be con nected to a peripheral device or simply be left unconnected Note that unless there are specific reasons such as to optimize the network traffic to suit better the application the routing ta
395. nly one single I O process on the separate processor and that you pass along the com mands or data as soon as possible to minimize the communication delay In addition as the T225 has a demultiplexed bus interfacing with it through memory is very simple Some people have build a prototype A D card with it in a single day and using only a minimum of components b Interface the peripheral device through a link adaptor A link adaptor converts between a serial link protocol and a parallel 8 bit sys tem This enables to read and to write to the peripheral device as a normal channel Various transputer modules such as DACs ADCs and graphics TRAMs that exploit this scheme are available from transputer board ven dors c Memory map the device This means that you set up a dataregister at a certain memory location pref erably outside the normal memory space and that you read from it or write to it as a normal memory location In order to activate the handling process and to avoid expensive polling loops you will probably need an interrupt provided for example by the event pin The equivalent of vectorising inter rupts can be achieved by using an additional memory mapped register that holds some status or address related to the peripheral device You can safely read or write to memory mapped registers from within your Virtuoso tasks 33 11 Performance results 33 11 1 Single processor version v 3 0 The native tra
396. nsigned integer that holds a bit mask where each bit that is set to one indicates a group that the task belongs to JoinGroup can be used to associate the active task with the taskgroup given in the argument LeaveGroup removes this association KTaskGroup The class that is used to make objects corresponding to groups of tasks has P2 180 Virtuoso Reference Manual Copyright 1996 Eonic Systems Microkernel C interface the name KTaskGroup The class definition is as follows class KTaskGroup private K_TGROUP m_TaskGroupID construction destruction public KTaskGroup K_TGROUP taskid access functions public K_TGROUP GetID const operations public void Start void Abort void Suspend void Resume implementation private The constructor takes the task group ID number as an argument The GetID member function allows to retrieve the ID of a task group object Other member functions called upon a KTaskGroup object will result in ker nel service calls with the task group ID of the task group object as the first argument The mapping between member functions and kernel services is the following taskgroup Start calls KS_Start TASKGROUPID taskgroup Abort calls KS_Abort TASKGROUP ID taskgroup Suspend calls KS_Suspend TASKGROUPID taskgroup Resume calls KS_Resume TASKGROUPID 17 6 KSemaphore Objects representing kernel semaphores are of the class
397. nsputer interrupt response can be fast typically 1 to 3 micro seconds 9 but in reality this is the lower limit as to the actual scheduling of a specific process one has to take account of the queue latency often resulting in tens of milliseconds of reaction times In the occam version and in the C version we obtained basic switching times of 6 microseconds on a transputer running at 25 MHz and using the internal RAM This means that the actual penalty is less than 5 microseconds while we gain the certainty that the process will be scheduled within a known interval The actual Virtu oso call takes longer since the kernel has to verify all pending messages timers and the priority Typically a kernel service will take a minimum of 20 microseconds on a 30 MHz transputer using 3 cycle external memory and in absence of floating point code When the FPU is in use the times obtained Copyright 1996 Eonic Systems Virtuoso Binding Manual T8 9 Virtuoso on the INMOS T2xx T4xx T8xx are increased with 16 microseconds 64 bit reals Below a summarizing table taken from the provided demo program gives performance details for the version 3 0 of Virtuoso These compare favorably with the figures obtained on other processors Note that the times for the buffered communi cation calls enqueue dequeue are essentially set up times which compare very favorably with other systems available for the transputer All times were measured in t
398. nt priority KS_SetPrio This variable is actually accessed via a macro and should be treated as read only This may be enforced by future versions of the microkernel or the variable may be replaced by a function Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 105 Alphabetical List of Virtuoso microkernel services 11 68 e SUMMARY e CLASS e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES KS Test Test a semaphore Semaphore int KS_Test K_SEMA sema The KS _Test microkernel service is used to test whether a specified event has occured The event must be associated with the given semaphore If the semaphore count is greater than zero the call returns RC_OK and the semaphore count is decremented by one Otherwise the calling task returns with an RC_FAIL RC_OK or RC_FAIL K_SEMA semaphore if KS_Test semaphore RC_OK printf semaphore was signalled n else printf semaphore not signalled n KS_TestW KS_TestWT KS _ TestMW KS _ TestMWT KS Signal KS_SignalM In Virtuoso Micro this service is implemented as a macro P2 106 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services 11 69 KS TestMW e SUMMARY Test multiple semaphores e CLASS Semaphore e SYNOPSIS K_SEMA KS_TestMW K_SEMA list e
399. nt server_pollkey void These functions poll the host server for a keyboard input the escape key used for starting the debugger resp UNS32 server_time void This function requests the environment of the host program the calen dar time and returns that value Higher level drivers Three drivers are provided that communicate with the hostserver using the call_server function of the low level driver Thanks to the use of system wide queues they permit any task to access the hostserver even if is located on a processor node that is not connected to the host These drivers are Vir tuoso tasks They must be defined in the SYSDEF file together with the used queues and resources P2 126 Virtuoso Reference Manual Copyright 1996 Eonic Systems Hostserver and netloader Driver Use Input queue Outputqueue Resource CONODRV Console_out CONOQ CONRES CONIDRV Console_in CONIQ CONRES STDIODRV Std I O STDIQ STDOQ STDIORES GRAPHDRV Graphics GRAPHIQ GRAPHOQ GRAPHRES Note The Borland PC version simulates the hostserver using a hostserver task The interface also uses two semaphores to synchronize the communi cation See the section on the 80X86 version for more details 12 5 0 a Console input and output The console drivers provide a character based input and output with the hostserver The following functions are provided KS_EnqueueW CONOQ char sizeof char Output a character Can be used from a remote p
400. nt xc int yc int a0 int al int r void ellipse int xc int yc int a0 int al int xr int yr Draws full lines rectangle circle circular arc or elliptical arc using current color and linestyle Notes 1 xc yc centre of circle or ellipse a0 a1 start and end angle of arc 2 r Xr yr radii The driver performs any necessary aspect ratio corrections so a circle will always be a real circle and not an ellipse even with non square pixels The next function can be used to read the x y values calculated by the driver void drawpoly int npoints int points Draws polygon The second parameter is an array of integers with alternating x and y coordinates To obtain a closed polygon repeat the first point at the end This is much more faster than repeated line drawing calls Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 137 Runtime libraries 13 2 5 Drawing filled forms void pieslice int xc int yc int a0 int al int r void sector int xc int yc int a0 int al int xr int yr void fillellipse int xc int yc int xr int yr void bar int left int top int right int bottom void bar3d int left int top int right int bottom int depth int topflag void fillpoly int n int points void floodfill int x int y int border Draws filled shapes using the current fill color or pattern P
401. nterface and if the Task Level Debugger is not present It is not the intention of this manual to lay out the internals of the host interface and the communication protocol between the host server program and the target board s Please contact ISI if more information is wanted on this topic For more details on the different levels of the host interface see Host server low level functions and Simple terminal oriented I O in the chapter of Runtime libraries The host interface device driver reserves event signal number 16 for its own use 27 11 Task Level Timings Following is a list of task level timings of some of the kernel services pro vided by Virtuoso These timings are the result of timing measurement on a Copyright 1996 Eonic Systems Virtuoso Binding Manual M1 25 Virtuoso on the Motorola 56K DSP 27 12 DSP56002 board with a clock speed of 40 MHz and zero wait state program and data memory All timings are in microseconds The C compiler used for the DSP56002 environment is the G56KCC from Motorola Minimum Kernel call Nop 1 10 Message transfer Send Receive with wait Header only 2 71 16 bytes 2 75 128 bytes 2 80 1024 bytes 2 126 Queue operations Enqueue 1 byte 1 22 Degqueue 1 byte 1 23 Engueue 4 bytes 1 26 Degqueue 4 bytes 1 26 Enqueue Dequeue with wait 2 64 Semaphore operations Signal 1 16 Signal Wait 2 52 S
402. ntly more difficult to design because they must not only deliver correct answers but they must also provide the answers at the right and at the predictable moment in time Failing to meet these hard real time deadlines can lead to fairly innocent effects as well as to catastro phes example airplane We also know soft real time systems These sys tems must deliver the answer most of the time within a statistically defined timing interval Missing some of these intervals is acceptable in most cases A typical example is a terminal One expects a reaction of the system within 2 seconds Faster is better but occasional longer reaction times are toler ated even a complete reboot if this is not needed too frequently e g your own PC Virtuoso was designed to be able to meet hard real time require ments but this also entails the capability to meet soft real time requirements How did technology provide solutions to meet hard real time requirements A simple and crude approach is to use enough resources without imposing limits to solve the problem Theoretically this is like using a Supercomputer to add 2 2 in all cases where that operation is an important aspect of the application Clearly this is an overkill and a waste of resources It is also very likely that it won t solve the problem as some applications simply require a different type of solution for example a distributed system Or worse when the reaction time is important often fast pro
403. o User Manual Copyright 1996 Eonic Systems Process Queue Resource Semaphore SP Suspend task System definition Task Timer A thread of execution with its own stack using the nanokernel API The difference between a process and an ISR is that the process may block or wait whereas the ISR must continue executing until it returns A structure providing buffered asynchronous communication between microkernel tasks Data is communicated in fixed size blocks Items are dequeued received in the same order that they were enqueued sent A microkernel object that is used to sequential ize operations of several tasks When a tasks locks a resource no other task may lock the same resource until the first task unlocks it A flexible means of synchronization of between tasks A task signals a semaphore to wake up a task that may be waiting on the semaphore Semaphores are counting allowing several tasks to signal and wait on one semaphore Single processor A product version that pro vides the full range of services within one pro cessor Temporarily halt the execution of a microkernel task and prevent it from being rescheduled until it has been Resumed A task in a waiting condition may be suspended Declaration of the target hardware and of microkernel objects and device drivers The specification of each object includes which node it is placed upon A thread of execution with its own stack
404. o label Fkernel_sign_entry to give the signal a A N An example is given for each class of ISR Example 1 a non signalling ISR uses registers D2 L D4 L RO and R1 move R7 prior increment of R7 move D2 L y R7 save D2 L move D4 L y R7 save D4 L move RO y R7 save RO move R1l y R7 save R1 lt body of ISR gt move R7 post decrements are faster move y R7 R1 restore RI M3 16 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Motorola 96K DSP move y R7 RO restore RO move y R7 D4 restore D4 L tel i move y R7 D2 restore D2 L rti finito Example 2 a signalling ISR using R4 and M4 as extra registers move R7 prior increment of R7 move DO L y R7 save DO L move D1 L y R7 save D1 L save RO move R4 y R move RO y R7 7 7 save R4 move M4 y R te save M4 lt body of ISR gt move R7 post decrements are faster move y R7 M4 restore M4 move y R7 R4 restore R4 NO DECREMENT move SIGNUM DO L load DO L with event signal number jmp Fkernel_sign_entry signal the kernel If a C procedure is called from an ISR all registers that are not preserved across a procedure call see paragraph 29 5 4 Subroutine Linkage for a list of preserved registe
405. o package is also delivered with 12 months support and mainte nance To make you eligible for these 12 months support and upgrades you must sign and return the license agreement to Eonic Systems or to your dis tributor So don t wait any longer and mail this license form today From now on this means you can submit any problem you would encounter by fax or by mail If the problem is really holding you up don t hesitate to call In addition during the 12 months following the delivery we come out with any upgrade software or manual we will ship you a new version shipping cost not included Bugfixes are always fixed when reported Cross development capability As the microkernel level is close to 100 identical for all target processors we have seen that a number of our customers have continued to use our evaluation kit on PC for cross development even if the target system is a rack with several tens of processors Therefore we decided to include this Borland version binary only with any license delivered P1 6 Virtuoso User Manual Copyright 1996 Eonic Systems Installation 1 7 The final reference While every effort was made to have this manual reflect the Virtuoso pack age the final reference is the source especially as some target processors or boards might impose small changes So if you are not sure about a library function first take a look at the include files h and the examples Copyright 1996 E
406. o switch to the next process To restart a terminated process repeat the calls to _init_process and _start_process When a PRHI process is swapped in AR3 points to the start of the PCS A process can create local variables by incrementing the initial stack pointer by the number of words required The first available word is the entry point field at ARS 7 37 4 Nanokernel communications A channel type is defined by a data structure and a number of nanokernel services that operate on it Each instance of the data structure is called a channel Channels can provide both process synchronization and data com munication The nanokernel does not itself use or create channels However the ser vices that operate on channels should be considered part of the nanokernel as they may modify the process FIFO or invoke the nanokernel swapper All channels have an internal state What exactly is represented by the state depends on the type of the channel typically this will be the occurrence of an event or the availability of data Copyright 1996 Eonic Systems Virtuoso Binding Manual Tl2 11 Programming the nanokernel An operation on a channel can consist of any combination of the following action types Wait A channel operation has a waiting action if the calling process can be descheduled as a result of the call The process is then said to wait on the channel Signal A channel operation has a signaling acti
407. o the T800 series For process control and fault tolerant applications the T9000 has a lot of options In addition there is now a protected mode and T9000 local mode as well including traphandlers Besides these interesting features the T9000 has 16 Kb on chip RAM still has two priority FIFO based queues and has an on chip Virtual Channel Pro cessor The latter enables in conjunction with a link switch very fast commu nication between any processor of the network As you can see a lot of the features of Virtuoso will even be faster on the T9000 while we will be able to implement the critical part of the kernel with more on chip support The main thing is that the programmers interface to Virtuoso will be almost identical delivering on the promise of portability across different technologies Copyright 1996 Eonic Systems Virtuoso Binding Manual T9 1 Virtuoso on the INMOS T9000 transputer T9 2 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Texas Instruments TMS320C30 amp C31 35 Virtuoso on the Texas Instruments TMS320C30 amp C31 35 1 Virtuoso versions on TMS320C30 C31 At this moment we support the microkernel level and one ISR level on the TMS320C30 C31 A port of the nanokernel as well as of the two level ISRs is undertaken and wil be released shortly Copyright 1996 Eonic Systems Virtuoso Binding Manual Tli 1 Virtuoso on the Texas Instruments TMS320C30 amp C31 35 2 TMS320
408. o this entry point and executes it with the current prior ity of the task In the Abort function the user should deallocate all acquired system resources such as memory and timers Application specific mea sures can be programmed here to assure the continuity of the application Class Timer This class of calls permits an application task to use a timer as part of its function by allocating a Timer object From then on the timer can be started to generate a timed event at a specified moment one shot or interval P1 26 Virtuoso User Manual Copyright 1996 Eonic Systems Functional support from Virtuoso cyclic This event can then signal the associated semaphore Timers are mainly used to regulate the execution of tasks with respect to a required timely behavior While the timer objects are relatively simple in nature using them correctly can be tricky The reason is that the designer not only needs to know when to start a certain task he must also take account of the worst case execution delay of his task A real system involves meeting deadlines and missing a deadline simply means that the system has failed Virtuoso efficiently manages multiple timers using an ordered linked list of pending timer events A timer for an event is inserted into the linked list in accordance with its duration A differential technique is used so that the timer with the shortest time to expiration is at the head of the list Timed events may even b
409. ocated in the same enclosure and processing nodes which are located on remote sites and interconnected using optical fibers over several km 6 3 Simulation in the control loop This is a promising area Until now most complex systems that need to be controlled electricity power plants chemical plants rely on an experienced operators But even with years of experience they can make mistakes espe cially in exceptional conditions Often it has been observed afterwards that the operator error could have been prevented if the operator would have got complete know how of the behavior of the system in these exceptional con dition e g a reactor failure The same applies for a change in the desired production level of a given product e g cracking installation The solution is to use simulators that work in parallel with the control system This is possi ble today but it requires a supercomputer to do it With a parallel machine this can be done in a cost efficient way while Virtuoso provides the neces sary real time characteristics 6 4 Fault tolerant systems Because Virtuoso provides complete transparency as to the location of objects in the system it is fairly straightforward to write application depen dent programs that have a degree of fault tolerance The solution is simply to provide passive or active backup copies of the active tasks on other pro cessors As a result we have then hardware and software redundancy On each proce
410. ocess is swapped out the return address and the INTSET registers remain on the stack of the interrupted process until it is swapped in again The code fragment below show the skeleton of an interrupt handler running at the ISR1 level Please note that the three instructions following an LAT are actually executed before the LAT itself push st push the INTSET registers push rll pusht rll lat SETISR1 JE nable interrupts ASAP push aro continue saving INTSET or push arl modify IIE IIF push ar2 body of ISR interrupts are enabled st rll ar0O ari ar2 available lat ENDISR1 nop any three useful instructions nop 7 e g pop registers not in INTSET nop or restore IIE IIF 37 7 Communicating with the microkernel As mentioned before the Virtuoso microkernel is implemented as a PRHI Copyright 1996 Eonic Systems Virtuoso Binding Manual TI2 17 Programming the nanokernel process It uses a single stack based channel to receive commands from the tasks the network drivers other PRHI processes and interrupt handlers A pointer to this channel is exported in the C variable K_ArgsP Two types of data can be pushed onto this channel 1 Small integers 0 63 are interpreted as events Events are simple binary signals that a task can wait for using the KS_EventW service Most events will be generated by interrupt handlers and driver processes For the C40 version event numb
411. ochCH sysdef pp RM sysdef pp The sysdef file for the D1P and D1Pobj sample is given below Based on this sysdef file sysgen will write the C specific files vkobjcts cpp vkobjcts hpp vkob1 cpp and vkob1 hpp The following observations can be made from these three files m The mapping of name ID s of kernel objects given in the sysdef file to C kernel object names in the CPP files m The presence of all kernel objects except memory maps in vkobjcts cpp Vkob1 cpp contains the node specific memory map object m The correct initialization of all C objects by passing the correct ID name in the definition of the objects This explicit passing of the name ID also allows explicitly defines the name mapping between ID names and C object names m The presence of one C object in vkobjcts cpp that is not defined in the sysdef file This is the ActiveTask object representing the currently active task These C files generated by sysgen also have to be compiled and linked in in the executables In general the compiled vkobjcts cpp file must be included in the executable for all nodes The node specific file s vkobnnnn cpp must only be linked in with the executable that has to run on node nnnn The user bears the responsibility to edit the makefile in an appro priate way A consequence of the fact that almost all kernel objects are defined in vkob jcts cpp is that all nodes will carry the overhead associated with the C
412. ode and link definitions and the node iden tifier is not present as an attribute of the objects As an example we provide here a possible system definition file Example System Definition File define BYTE 1 define WORD 4 NODE ROOT T8 DE NODE2 T8 DE NODE3 C40 DE NODE4 C40 oO ROOT NetLink_Driver 1 NODE2 NetLink_Driver 3 P2 142 Virtuoso Reference Manual Copyright 1996 Eonic Systems System Configuration NETLINK ROOT Netlink_Driver 2 gt NODE3 NetLinkDma 3 1 NETLINK ROOT Netlink_Driver 2 lt NODE3 NetLinkDma 0 1 NETLINK NODE3 NetLinkDma 1 1 NODE4 NetLinkDma 4 1 DRIVER ROOT HLO3_Driver wi DRIVER ROOT HostLinkDma 0 3 PRIO_ALT DRIVER NODE1 RawLinkDma 2 PRIO_DMA DRIVER NODE2 RawLinkDma 5 PRIO_DMA DRIVER ROOT TimerO_Driver tickunit IVER NODE2 TimerO_Driver tickunit taskname node prio entry stack groups j ed ifdef DEBUG TASK TLDEBUG ROOT 1 tldebug 400 SYS EXE TASK POLLESC ROOT
413. often by a pointer to an area in memory This methodology cannot operate across the boundaries of a processor as a pointer is by definition a local object Virtuoso solves this problem by a system wide naming scheme that relates the object to a unique identifier This identifier is composed of a node identifier part and an object identifier part This enables the microkernel to distinguish between requested services that can be provided locally and those services that require the cooperation of a remote processor As a result any object can be moved anywhere in the network of processors with out any changes to the application source code A possible mapping of objects into a real topology is illustrated in figure 1 Note that each object including semaphores queues and mailboxes could reside as the only object Copyright 1996 Eonic Systems Virtuoso User Manual P1 11 Virtuoso an overview on a node The key to this transparency of topology is the use of a system definition file see below In this context we emphasize that with Virtuoso the node identifier is nothing more than an attribute of the object The transparent distributed operation would not work if the semantics of the microkernel services and their implementation were not fully distributed This imposes a certain programming methodology E g global variables or point ers are only allowed if the programmer very well knows that only local refer ences to it are used and the ob
414. ogrammer from the burden of doing it himself It must also be noted that for multiprocessor targets multitasking is a must to achieve high perfor mance because without it it is not possible to overlap computation and cal culation As such the microkernel must correctly provide for priority driven preemptive scheduling of the tasks permit to transfer data between the tasks in a synchronous and asynchronous way coordinate tasks deal with timed events allocate memory and protect common resources In addition the microkernel should be small secure and flexible while providing a very fast response Practice has shown that in general the same set of microker nel services is sufficient P1 10 Virtuoso User Manual Copyright 1996 Eonic Systems Virtuoso an overview 3 2 2 Classes of microkernel services The Virtuoso programming system is built around a second generation real time microkernel It provides the same API by way of a virtual single proces sor model independently of the number or type of interconnected processors that are actually being used from single 8 bit microcontrollers to multi 32 bit processor systems This approach also means that the programmer can continue to use his single processor experience and start using multiple pro cessors with a minimum of effort The Virtuoso programmer s model is based on the concept of microkernel objects In each class of objects specific operations are allowed The main object
415. okernel process level 4 The Virtuoso microkernel C task level 4 8 1 The ISR levels At the ISR level the user controls himself how much context he uses and he is responsible himself for saving the context In practice this can be 1 or 2 registers ISR s talk directly with the interrupt hardware of the processor The user should in most cases perform at most two actions at the ISR level 1 Accept the interrupt e g at the ISRO level 2 Handle the interrupt if needed e g at the ISR1 level On most processor types e g microcontrollers these two levels are not dis tinguished When the ISR has completed a cycle e g filled up a buffer area he must signal the microkernel by raising an event The task that should fur ther process the data must wait on it by issuing a KS_EventW ISR micro kernel service When the event is raised the task becomes runable again Note that interrupts are disabled during the execution time of the ISR if this method is used Hence ISR s should be kept short In order to accommodate more demanding applications typically to be found in the DSP area interrupt levels were split In these implementations the ISRO only accepts the interrupt and then leaves further handling of the inter rupt to a level were interrupts are enabled again This is a very short opera tion hence interrupts are only disabled for a few clock cycles In the next step of processing the ISR1 level can be used The ISR1 inte
416. olution the number of timer counts are returned On the 21020 the count is equal to a period of the clock frequency In low resolution the number of kernel ticks are returned A kernel tick is a multiple of timer count and defined in the main function As this value is a 32 bit wraparound value it is more intresting to calculate the difference between two values read out consecutively However to facilitate this kernel service KS_Elapse is written for this purpose See the Alphabetical List of Virtuoso kernel services earlier in this manual for a full description of these kernel services The timer device driver reserves event signal number 4 or 14 depending on the priority for its use As the host interface uses event number 8 selecting 4 will allow the timer interrupt to interrupt the host interface ISR while select ADI 48 Virtuoso Binding Manual Copyright 1996 Eonic Systems Predefined drivers ing 14 can delay the processing of the timer ISR Note In our newest versions of VIRTUOSO CLASSICO and MICRO the timer is always signalling event number 48 20 0 2 The host interface device driver The host interface driver is installed by calling procedure init_server In the examples that accompany the release of the Virtuoso kernel the installation of the host interface is done in procedure main The host interface driver can be used on two levels The lowest level needs only one kernel resource HOSTRES which
417. on if a waiting process can be rescheduled as a result of the call If the current process is the PRLO process a process swap will be performed Test amp modify A test amp modify action modifies the state of a channel and returns infor mation about it without changing the execution state of any process Three channel types are predefined in the current nanokernel implementa tion It is possible to create new channel types if necessary an example will be given at the end of this chapter A full description of the nanokernel ser vices for each of these channel types can be found in the alphabetical listing in the next chapter 37 4 1 C_CHAN Counting channel This is an implementation of a counting semaphore It is typically used by interrupt handlers to reschedule a process that was waiting for the interrupt The C_CHAN structure has two fields 0 CH_PROC pointer to the PCS of a waiting process or NULL 1 CH_NSIG event counter Two nanokernel services are available for this channel type PRHIL WAIT wait action PRHI_SIG signal action 37 4 2 L_CHAN List channel This type of channel maintains a linked list of memory blocks using the first word in each block as a link pointer The microkernel uses this type to imple ment its free lists of command packets data packets and timers If used for data communication it behaves as a LIFO buffer TI2 12 Virtuoso Binding Manual Copyright 1996 Eonic Systems Programmin
418. on inside the nanokernel is performed using channels Sev eral types exit The simplest type is used for synchronization and corre sponds to a counting semaphore The other types are used for data transfer The possiblity is provided that a user can add his own channel types The microkernel who manages the tasks is build as an application on top of the nanokernel The main component is a PRHI process that executes com mands it receives from a channel When the channel is empty the microker nel looks for the next task to run replaces the nanokernel IDLE process by that task and performs the additional register swappings required for C tasks The nanokernel is not aware of the manipulations performed by the micro kernel As far as it concerned there is only one PRLO process which it exe cutes whenever no PRHl process is ready to continue This makes it possible to use the nanokernel on its own 18 10 2 Internal data structures The user does not normally need to access the internal data structures used by the nanokernel The documentation in this section is provided only for a better understanding of how the nanokernel operates A process is represented by a pointer to a Process Control Structure PCS For PRHI processes the PCS occupies the first six words of its stack Two Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 19 Virtuoso on the Analog Devices 21020 DSP 18 10 3 entries are placed at the to
419. on what action must be taken when the service cannot be provided immediately The first type of the service returns with an error code when the service is not available The second type will wait until the service is available As this can be forever the third type of the service permits to limit the waiting period to a certain time interval expressed in timer ticks The suffixes used to distinguish the three variant types are as follows 1 No suffix no waiting returns an error when not serviced 2 W wait till service available 3 WT wait till service available or timeout expires Two other suffixes are used as well 1 M to indicate that the service operates on a list 2 G to indicate that the service operates on a set of taskgroups Important note While Virtuoso is ported as much as possible with the same API to all processors it is possible that particular processors have a slightly different API especially if the service is processor specific Always verify the correct syntax in the iface h include file if you encounter errors when compiling The source is always the ultimate arbiter Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 11 Virtuoso microkernel services 8 3 Task control microkernel services a start a task from its entry point void KS_Start K_TASK task m start a set of taskgroups void KS_StartG K_TGROUP taskgroup m suspend a task void KS_Suspend K_TASK task
420. onic Systems Virtuoso User Manual P1 7 A short introduction 2 A short introduction 2 1 The one page manual When using Virtuoso the programmer will develop his program along the fol lowing steps We outline here the steps for the use of Virtuoso Classico as this entails all levels supported by Virtuoso 1 Define the essential microkernel objects used as building blocks for the appli cation These are the tasks the semaphores the queues the mailboxes the resources and the timers If the target is a multiprocessor system the user will need to define the network topology as well This is achieved by prepar ing a description file called sysdef in text format Sysgen normally invoked when calling the make utility then reads the sysdef file and gener ate one c and one h include file per processor node This work is facili tated by the use of a makefile and grouping the tasks in a library 2 Write and debug the tasks as normal independent programs that cooperate using the microkernel services Develop lower level ISRs and drivers can be nanokernel processes Compile and link Load the target system and run the application oa Ff Ww Debug and fine tune it using the debugger and tracing monitor In order to exploit the real time features the Virtuoso microkernel is linked with the user tasks and runs as a single executable image on each proces sor This approach results in faster and smaller cod
421. ons Mi 11 Parameter Passing sisir hirii sorea al A aN Dion laye teee M1 11 Subroutine Gall sequence Wi cccteiedsiinin deeense add deieeiet hee eeedaeeee M1 11 Procedure Prologue and Epilogue cccs ceseeeeeeeeeeseneeeeeeeeeeneeeneeenee erena M1 12 Stack Layout nanena pea a Ea EA T lat at ARAE teal A AEAEE eai M1 13 Interrupt Service Routines ISR ccvesesecseves altencciaviereteaseddeeetatentoviadoeenleed te ctocaters M1 14 ISR Conventions gatos tee aes a eal cele set arene the ds eu cete acto meray Sachin cen nucta eh M1 14 Alphabetical list of ISR related services cecccceeeceseeeeeeceeeeeseeeeeeeeeeeceeeeneeeeeens M1 18 Developing ISR routines sche we cats eclidsed rea pace Aue atc aed te ade sande dae casas ae eat M1 23 The nanokernel on the 56002 s ic 53 che dg scrceeclaes enti Mievdetedn eeatoondt aden M1 23 Predefined drivers scs ta deen Sect to eth Acatcaate ont qua vetoes aa ateutarhanereres met uactaqeesientelenttctts M1 23 The timer GEVICE GIVER ssccpcice content ces ntys wechemn bee gle eed ero M1 24 The host interface device driver eeeeeeeeeeseeceeeeeeeeeeneeeeeee eeeeeeneeteaeeeeaeaas M1 24 Task Level Timings seissen ninien eaa aoo ere iawn tea aa TEE Enan M1 25 Application development hints ccceaxecase cd cage tenpcodecrtieretenle cet ode laeidees de gasiae M1 26 Virtuoso on the Motorola 68030 systems M2 1 Source files of the Virtuoso kernel oc ccsseetesnchoeectanie
422. or obstacles had to be overcome The first was to find the algorithm that converted the FIFO scheduling mechanism into a preemptive scheduling mechanism The second was how to implement the kernel in such a way that user tasks could safely interact with the special I O hardware of the trans puter Both problems were solved in a satisfactory way using occam and C with a minor amount of assembler inserts In addition we were happily sur prised to find that the implementation on the transputer is one of the fastest available when compared with other processors running at the same speed In order to understand the importance of this key issue it is worthwhile to have a closer look at the FIFO transputer scheduler mechanism On the transputer the compiler will generate for each user defined process a startp instruction In order to start a process needs to be initialized with its Workspace Pointer Wpir and its Instruction pointer Iptr Whenever a new process is started normally from within the first started process a FIFO T8 4 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the INMOS T2xx T4xx T8xx process queue implemented as a linked list is build up This is achieved by adding the new process at the back of the queue Once started a process can be descheduled for the following reasons 1 Because it has to wait on a communication with another process via an external link via a soft channel in memo
423. ord or where sizeof does not return the number of 8 bit bytes in a type Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 43 Alphabetical List of Virtuoso microkernel services 11 17 e SUMMARY e CLASS ey ee e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES KS EnqueueW Insert entry into a FIFO queue with wait Queue int KS_EnqueueW K_QUEUE queue void data int size KS _EnqueueW inserts an entry into a FIFO queue If the queue is FULL the calling task is put into a waiting list in order of its priority When the queue becomes NOT FULL the entry is inserted into the queue RC_OK if operation succeeds RC_FAIL otherwise typedef struct float X Y POINT POINT next_point K_QUEUE POSITION int RetCode put X Y coordinates in the POSITION queue if queue is full we wait for space si RetCode KS_EnqueueW POSITION amp next_point sizeof POINT if RetCode RC_OK printf failed to queue co ordinates n KS_Enqueue KS _EnqueueWT KS _Dequeue KS _DequeueW KS _DequeueWT The size parameter is the number of 8 bit bytes to be queued It should be P2 44 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services equal to the width of the queue which implies enqueueing only one entry at a time o
424. ore count is greater than zero the call returns RC_OK and the semaphore count is decremented by one Otherwise the calling task returns with an RC_FAIL RC_OK or RC_FAIL K_SEMA semaphore if KS_Wait semaphore RC_OK printf semaphore was signalled n else printf semaphore not signalled n KS_WaitT KS_WaitM KS_WaitMT KS_ Signal KS_SignalM In Virtuoso Classico this service is implemented as a macro P2 114 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services 11 76 e SUMMARY e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES KS WaitM Wait on a list of semaphores Semaphore K_SEMA KS_WaitM K_SEMA list The KS WaitM microkernel service performs the same function as the KS_Wait microkernel service except that it uses a semaphore list This func tion operates as a logical OR The occurrence of an event associated with any one of the semaphores in the list will cause resumption of the waiting task Semaphore identifier of the event that occurred or the predefined constant ENDLIST if no semaphore was signalled K_SEMA Event K_SEMA iistl SWITCHI1 SWITCH2 TIMERA ENDLIST Event KS_WaitM Listl test for any of 3 events KS_ Wait KS_WaitT KS_WaitMT KS_ Signal KS_SignalM In the si
425. ormat INT 8 Memory GLO 2 Memory definitions P2 151 Memory Management P2 18 Memory maps P2 10 Message GLO 2 Message services P2 14 messages P2 170 Copyright 1996 Eonic Systems Messages and Mailboxes P2 6 Microkernel GLO 2 microkernel level P1 15 microkernel services P1 11 P2 11 Microkernel types P2 3 P2 177 MODE 1 register and MODE2 register ADI 5 Motorola 68030 M2 1 Motorola 96K DSP M3 1 Move Data GLO 2 moverel P2 136 moveto P2 136 multi level approach P1 13 multiple processor operation P1 39 multi tasking P1 10 N nanok_yield C40 ADI 47 ADI 34 TI2 47 Nanokernel GLO 2 Nanokernel ISR management P2 24 nanokernel level P1 14 Nanokernel linked list based services P2 24 Nanokernel process management P2 23 Nanokernel processes and channels P2 21 Nanokernel semaphore based services P2 24 Nanokernel services P2 23 Nanokernel stack based services P2 24 Network file P2 122 Node GLO 2 Node description P2 145 O Object GLO 2 Objects P2 141 Once only synchronization P1 32 Other graphical calls P2 139 outtext P2 139 outtextxy P2 139 P Parallel processing P1 18 parallel processing P1 22 PC interrupt drivers I1 1 PC stack PCSTK and PC stack pointer PCSTKP ADI 9 pieslice P2 138 Predefined drivers ADI 48 ADI 35 prhi_get C40 ADI 38 ADI 25 TI2 32 prhi_getw C40 ADI
426. oth are 32 bit registers Each bit in the registers is representing an interrupt The interrupt bits are ordered by priority highest gt lowest Setting bits in the IRPTL acti vates an interrupt Example Bit set IRPTL SFTOI activates software interrupt Bit clr IRPTL SFTOI clears a software interrupt An interrupt can also be masked Masked means that the interrupt is dis abled Interrupts that are masked are still latched so that if the interrupt is later unmasked it is processed Example Imask 1 unmasked enabled 0 masked disabled Interrupts 0 and 1 are not maskable Bit IR Address Function 0 0x00 Reserved for emulation 1 0x08 Reset 2 0x10 Reserved 3 0x18 Status stack loop stack PC stack 4 0x20 High priority timer 5 0x28 IRQ3 asserted 6 0x30 IRQ2 asserted 7 0x38 IRQ1 asserted 8 0x40 IRQO asserted 9 0x48 Reserved 10 0x50 Reserved 11 0x58 Circular buffer 7 overflow interrupt 12 0x60 Circular buffer 15 overflow interrupt 13 Reserved 14 0x70 Low priority timer 15 0x78 Fixed point overflow ADI 8 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Analog Devices 21020 DSP 16 0x80 Floating point overflow exception 17 0x88 Floating point underflow exception 18 0x90 Floating point invalid exception 19 23 0x98 0xb8 Reserved 24 31 Oxc0 0Oxf8 User software interrupts 0 7 18 4 5 Program memory Data memory interface control r
427. outer that will locate the processor where the service or resource is located The router will then select the communication port to reach the desired processor The router itself manages a pool of mes sage buffers These buffers are dynamically allocated In addition the micro kernel messages indicate the priority of the requesting task As such the outgoing buffers are rearranged so that older messages with a lower priority will never block the more recent ones with a higher priority This can in practice be guaranteed because the granularity and hence the delay involved of a communication is about the same as the invocation of a microkernel service Because communication is considered as a microkernel activity it is very unlikely that the routing will hold up any task In practice it is so that Virtuoso can almost be considered as a system that implements some kind of virtual common memory This was achieved by implementing a router that handles all data transport including remote memory operations This way memory copying and message routing are considered as the same type of operation The result is speed as these operations shortcut the lay ered architecture The memory operations are the only active operations by the router that involve part of microkernel services All other messages are passed on to the communication port drivers e g links or to the different kernel agents This mechanism of ordering all requests in order of prio
428. ow the instructions provided on the screen while having a look at the rel evant sections of the Reference Manual To start developing a new application it is recommended to start from an example program and to copy it to a new directory where you will develop it 6 The supplied test program runs as a program on a processor connected to the host Exit from the demo with CTRL C or terminate the server to return to DOS While dip is not compiled with the debugger options most other examples are The debugger is started by hitting the ESCAPE key A good way to familiarize yourself with Virtuoso is to play a bit with the exam ple programs See what happens when you invoke the debugger while the benchmark loop is running or change the source to invoke the debugger task from within another task Using the debugger inspect the different ele ments of the system while you look up the meaning of the information pro vided in Part 2 of the manual You might find that the user interface is simple but remember that this way any terminal can do the job enabling Virtuoso to be used in exactly the same way when developing software for different tar get processors using different host systems To really have a look at how a multitasking kernel works we advise you to select the L List the last scheduling events at different moments when the benchmark is running You will certainly remark the microsecond accuracy with which the Virtuoso kernel is able
429. p by reason of a decrementing stackpointer A static PCS is used for the Idle process More details on the PCS will be intro duced in the section on process management A channel is represented by a pointer to a Channel Data Structure CDS The first word of a CDS is a pointer to the PCS of a process waiting on that channel or NULL Other fields depend on the type of the channel and will be introduced in the section on nanokernel communications The following static variables are used by the nanokernel to keep track of the state of the system NANOK_PRHI Pointer to the PCS of the current PRHI process or NULL if there is none NANOK_HEAD Head pointer for a linked list of PRHI processes that are ready to run When the current PRLO process is swapped out the PRHI process at the head of the list is removed and becomes the current process NANOK_TAIL Tail pointer for a linked list of PRHI processes that are ready to run When a process becomes ready to execute it is added to the tail of the list NANOK_PRLO Pointer to the PCS of the PRLO process This is a constant as far as the nanokernel is concerned The microkernel modifies this pointer NANOK_CRIT This is the number of interrupt handlers running with global interrupts enabled that are not yet terminated The process swapping is dis abled while this value is not zero On the 21020 the return address of the interrupt is stacked on the PC stack So we do not need an extra varia
430. pace can be calculated upon independently while interchanging intermediate values with the other subspaces In process control the parallel nature is even more apparent For example a data sampler reads some data in and passes it on for further processing while still another process processes the results for acting upon the controlled system The use of processes is not new for people who are familiar with operating systems or real time applications Their use is the only way to manage the Copyright 1996 Eonic Systems Virtuoso Binding Manual T8 1 Virtuoso on the INMOS T2xx T4xx T8xx 33 3 complexity The main reason normal application programmers were not allowed to use this mechanism is that most processors have no provisions to support processes and data communication The only way out is a soft ware based implementation resulting in important performance losses In addition no languages were available that supported real parallel constructs in the language itself INMOS changed all that by designing in a first step a simple parallel lan guage called occam and in a second step by building the transputer as a virtual occam machine What this means in hardware terms is that the trans puter is a classic 32bit processor 10 Mips at 20 MHz with some novel fea tures 1 Instructions for process creation and termination 2 Instructions for data communication 3 A microcoded FIFO scheduler 4 Two priority level
431. perating system because it only con centrates on the services needed for a real application and leaves the devel opment environment to the host station Virtuoso can be regarded as a real time operating system where all objects tasks etc are defined at the initial ization of the system In the future Eonic Systems will release versions that support dynamic creation and deletion of system objects as well as fault tol erant versions During the design major efforts also went into making sure that Virtuoso is a future proof programming tool With today s very fast technological changes this is a necessity because technology can evolve faster than the time it takes to design an application Therefore choices were made that enable the user to develop his applications mostly independently of the technology he uses This was achieved by opting for the use of portable ANSI C as a programming language and by adopting a virtual single processor model even if multiple processors are involved The fact that we have been able to port Virtuoso to new processors in less than two weeks proves the point Parallel processing the next logical step Some people regard parallel processing as a new technology The question is whether this is really so In our opinion this is more a natural result of the evolution of technology The point is that because of the growing level of inte gration of VLSI devices we have now mass volume production of complete
432. phore Semaphore0 SEMO Semaphorel SEM1 Semaphore2 SEM2 Semaphore3 SEM3 Semaphore Semaphore4 SEM4 Resource HostResource HOSTRES Resource StdioResource STDIORES Resource DemoResource DEMORES KMailBox Mailboxl MAILB1 17 13 2 node stripped out It is then also the users responsibility to remake these stripped down files each time the vkobjcts cpp file is regenerated Changes to the program files The file with the main function is situated in main1 c for the D1P sample and in main1 cpp for the D1Pobj sample Two blocks of changes can be distin guished here The first is related to the fact that main1 cpp is a C file that must link with C functions The second change involves the use of the C objects to start the tasks in the EXE group Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 191 Microkernel C interface In main1 c we find the following lines finclude iface h include nodel h include _stdio h extern int kernel_init void extern int kernel_idle void extern int netload void In main1 cpp these lines are wrapped in an extern C construct to ensure proper linkage extern C include iface h include _stdio h extern int kernel_init void extern int kernel_idle void extern int netload void In the main function the tasks in the EXE group are started This is accom p
433. pollesc 128 EXE endif TASK CONIDRV ROOT 2 conidrv 128 EXE TASK CONODRV ROOT 3 conodrv 128 EXE TASK GRAPHDRV ROOT 4 graphdrv 128 EXE TASK WLMON1 ROOT 10 wlmon 256 WLM TASK WLMON2 NODE2 10 wlmon 256 WLM TASK MASTER ROOT 5 master 256 EXE TASK WLGEN ROOT 20 wlgen 256 EXE TASK DIGIT11 ROOT 15 digitll 256 DIG TASK DIGIT12 NODE2 14 digit12 256 IG TASK DIGIT13 NODE3 13 digit13 256 IG TASK DIGIT14 NODE2 12 digitl14 256 IG TASK DIGIT15 ROOT 11 digit15 256 DIG TASK DIGIT41 NODE2 15 digit4l1 256 IG TASK DIGIT42 NODE3 14 digit42 256 IG TASK DIGIT43 NODE2 13 digit43 256 IG Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 143 System Configuration TASK DIGIT44 ROOT 12 digit44 256 DIG TASK DIGIT45 NODE4 11 digit45 256 DIG queue node depth width x ifdef DEBUG QUEUE DEBUGIN ROOT 16 4 endif QUEUE CONIQ ROOT 16 1 QUEUE CONOQ ROOT 256 1 QUEUE GRAPHIQ ROOT 16 4 map node blocks blsize ey MAP MAP1 ROOT 4 1K mailbox node 4E MAILBOX MAILB1 ROOT sema node pie me SEMA CTICK ROOT SEMA SM11 ROOT SEMA SM12 NODE2 SEMA SM13 NODE3 SEMA SM14 NODE4 SEMA SM15 ROOT SEMA SM16 NODE1 resource node RESOURCE HOSTRES ROOT RESOURCE CONRES ROOT RESOURCE GRAPHRES ROOT T 14
434. priority task in the system all other tasks are suspended Interrupts are serviced as usual while the debugger is active but the system TICKS timer will ignore its interrupt so that itis effectively halted Therefore time spent in the debugger is invisible at the task level Tightly integrated with the task level debugger is the tracing monitor This lists an execution trace of the events that were seen at the microkernel level and sometimes at the ISR level The task level debugger and tracing monitor can be removed by relinking the application without the debugger and tracing specific parts Disabling the DEBUG switch in the makefile will automatically regenerate a new applica tion without the debugger and tracing monitor Make sure that you follow the outline for the makefile and sysdef file of the examples provided Entry into the debugger Invoking the debugger from the keyboard The POLLESC task driver will intercept the ESCAPE key and start the debugger when this key is pressed Note that this happens only 10 times per second and that ongoing activity that uses the host resource like stdio will be finished first before the debugger can get access to the host and starts up P2 154 Virtuoso Reference Manual Copyright 1996 Eonic Systems Debugging environment under Virtuoso Once the debugger is entered the version of the debugger is displayed as VIRTUOSO TL Debugger 3 09 NODE 1 NODE Started by user in
435. ption define BUFSIZ 512 Default buffer size use by setbuf function define MAXBLKSIZE 0x4000 internal use define MAXPACKETLEN 256 internal use define MAXFILEPTRS 32 internal use define MAXSTRINGLEN 240 maximum string length define MAXPATHLEN 220 maximum path length define MAXFMODELEN 20 internal use These limitations find their origin in the communication protocol The com munication protocol uses 64 words The first word is the header followed by a command and or the data 13 1 2 Standard I O functions _stdio h standard input output functions FILE fopen const char path const char mode FILE freopen const char path const char mode FILE stream int fclose FILE stream int fgetc FILE stream P2 128 Virtuoso Reference Manual Copyright 1996 Eonic Systems Runtime libraries int fputc int c FILE stream int ungetc int FILE stream char fgets const char string Ine ony FILE stream int fputs const char string FILE stream char gets char string int puts const char string size_t fread void ptr size_t size size_t nmembs FILE stream size_t fwrite
436. quency of the hard ware timer used to generate the TICKS time TIICKTIME the TICK period in microseconds TIICKUNIT the TICK period in CLCKFREQ units TICKFREQ the TICK frequency in Hertz The number of available timers command packets and multiple wait packets are also defined in this file How much you need of each depends on your application but the following guidelines may be followed Timers are used to implement time outs at most one per task and can also be allocated by a task A command packet will be needed for each timer allocated by a task Com mand packets used for calling a kernel service are created on the caller s stack and should not be predefined A multiple wait packet will be needed for each semaphore in a KS_WaitM service call for as long as it remains waiting MAIN1 C also defines some variables used by the console driver tasks the clock system the debugger task and the graphics system These are included automatically if you use the standard names for the required kernel objects PMAIN ASM start up assembly code MAKEFILE The makefiles supplied in the EXAMPLES directory can easily be modified for your application They also show how to organize things so you can optionally include the task level debugger If you want to include the task level debugger put the corresponding definitions out of comment VIRTLIB LIBS virtosd lib DD dDEBUG DDD P DEBUG
437. r two distinct reasons 1 The queues are 4 bytes wide and a graphic command packet can take any number of words While a packet is being sent to the driver other tasks must be blocked from interfering 2 Tasks should not be allowed to modify the graphics context current color position textsize etc while another task is using the graphics server For this reason a lock and unlock call built into every function would not be sufficient Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 131 Runtime libraries To use the graphics calls you should Lock GRAPHRES Restore your graphics context if necessary Perform the plotting actions Save the graphics context if necessary Unlock GRAPHRES a A WO N The original Borland functions used to read the current context are some what impractical if frequent saving and restoring is required For this reason these calls have been modified to use a more symmetric syntax Most of these now take the same predefined struct as a parameter for both reading or writing a selected part of the context For some other calls the syntax has been modified for technical reasons e g it doesn t make sense to have pointers into to the PC memory space on a transputer Most graphics functions are of void type and will not even wait for anything to return on the GRAHIQ queue This means that graphics actions are not nec essarily executed when the interface functions r
438. r unpredictable side effects may occur Care needs to be taken when specifying the size parameter on systems where characters are stored one per word or where sizeof does not return the number of 8 bit bytes in a type Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 45 Alphabetical List of Virtuoso microkernel services 11 18 e SUMMARY e CLASS ey ea e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE KS EnqueueWT Insert an entry into a FIFO queue with timed out wait Queue void KS_EnqueueWT K_QUEUE queue void data int size K_TICKS ticks KS _Enqueue inserts an entry into a FIFO queue If the queue is FULL the calling task is put into a waiting list in order of its priority until the QUEUE NOT FULL condition or until the timeout expires When the queue is NOT FULL the entry is inserted into the queue RC_OK or RC_TIME if timed out typedef struct float X Y POINT POINT next_point K_QUEUE POSITION int RetCode put X Y coordinates in the POSITION queue if queue is full we wait for a maximum of 100 ticks x RetCode KS_EnqueueWT POSITION amp next_point sizeof POINT 100 if RetCode RC_TIME printf timed out queueing co ordinates n P2 46 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services SEEALSO KS _Enqueue KS _Enque
439. rademark of Eonic Systems Inc Virtuoso Classico is a trademark of Eonic Systems Inc Virtuoso Modulo is a trademark of Eonic Systems Inc Virtuoso Molto is a trademark of Eonic Systems Inc RTXC is a trademark of A T Barrett amp Associates TRANS RTXC is a trademark of Eonic Systems Inc RTXC MP is a trademark of Eonic Systems Inc RTXCmon is a trademark of Eonic Systems Inc INT 6 Virtuoso User Manual Copyright 1996 Eonic Systems The history of Virtuoso The history of Virtuoso Welcome to the world of Virtuoso We think that you have purchased one of the most versatile and unique systems available for the implementation of a real time system be it on a single or on a multi processor target system Before we jump into the details we would like to spend a few moments to explain the philosophy behind Virtuoso In 1989 Intelligent Systems International which later became Eonic Sys tems was founded At that time the INMOS transputer was the only proces sor available with in built support for parallel processing however it lacked the ability to support tasks with multiple levels of priority In order to apply this technology to hard real time applications ISI wrote a multi tasking ker nel for the transputer Derived from RTXC ISI added support for multiple processors and launched a product called TRANS RT XC In addition ISI started to port to a variety of other processors This was pos sible because
440. ram hstdio c C source file of the standard Input Output interface rtxh h include file with additional definitions siotags h include file with the standard Input Output tags makefile makefile for the server program server Inf link list file for the server program The makefile presumes that the directory structure for the server program is as follows M2 10 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Motorola 68030 systems h0 SERVER CMDS h0 SERVER SOURCE RELS The makefile also presumes that the mailbox driver routines reside in direc tory nO MBDRIVER and that OS 9 libraries are to be found in directory h0 LIB 28 5 3 Use of the server program The server program can be started just by typing server If one starts the server this way the name of the executable for the target processor board will be prompted for Alternatively the name of the executable can be given as a parameter for example server demo If the target processor board has to get a fresh executable it always has to be reset first Some options can be used on the server program c the server presumes that the target processor board has already running an application on it and will not load an executable on the target processor board The server will signal the target board that it has started again and resumes operation With this option no executable file name is to
441. ram code and string literals cinit initial values see remark below const string literals and switch tables data not used see remark below bss global and static variables stack system stack argument passing and local variables sysmem dynamic allocation memory pool Contrary to normal COFF conventions the C compiler does not use the data section for initialized data This is placed instead in bss and initialized at load time ram model or at run time rom model from data tables in the cinit section All assembly language modules in the Virtuoso system use the same method to allocate static data objects In addition to the standard sections listed above the Virtuoso system cre ates some special sections These are used to enable placement of critical pieces of code or data in fast internal RAM to enhance performance The Virtuoso special sections are nanok_code nanokernel code nanok_idle process control structure for the low priority process minik_code microkernel swapper code minik_stck stack for the microkernel process minik_args microkernel input channel TI2 6 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Texas Instruments TMS320C40 system_vec interrupt and trap vector table Of these nanok_code and minik_stck have the most profound effect on sys tem performance Some of the other special sections may be removed in future versions Copyright 1996 Eonic Systems Virtuoso Bi
442. rce is marked BUSY to prevent others from using it The logical resource can be anything such as a shared database non reentrant code an I O server etc Nested lock requests by the current owner are sup ported KS_Unlock requests by non owners are ignored e RETURN VALUE RC_OK EXAMPLE K_RES GRAPHRES void KS_LockW GRAPHRES moveto 100 100 lineto 200 100 KS_Unlock GRAPHRES SEEALSO KS _LockW KS_LockWT KS_ Unlock KS _UnlockwW KS _UnlockwW P2 66 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services 11 35 KS LockWT e SUMMARY Lock a resource with timed out wait e CLASS Resource e SYNOPSIS int KS_LockWT K_RES resource K_TICKS ticks e DESCRIPTION The KS_LockWT microkernel service provides a way of protecting a logical resource If the resource is already owned by another task at the time of request the calling task is inserted in the waiting list in order of priority The calling task is removed from the waiting list at the moment the resource becomes available or if the time out expires If the resource is available the resource is marked BUSY to prevent others from using it The logical resource can be anything such as a shared database non reentrant code an I O server etc Nested lock requests by the current owner are supported However KS_Unlock requests by non owners are ignored
443. receiver tasks that have matching message headers The datatransfer happens after synchronization eventually in the background FIGURE 8 The mailbox permits a selective transport between two tasks This is to ensure that the receiver task is ready to accept the data while avoiding that routing buffers are needlessly being filled up With the KS_ReceiveW call the two operations are done automatically by the micro kernel but the user must know beforehand where he wants the data to go He has the possibility to decide where to put the data by receiving the mes sage header separately Depending on its contents he can then decide on where to put the data by issuing the ReceiveData call Messages work with arbitrary sizes and permit a selective transport between sender and receiver including the specification of the priority of the mes sage In practice it was not possibly to use the single processor semantics of most real time kernels within Virtuoso The reason is that one can t pass pointers from processor to processor While the microkernel could test for locality we are forced to pass a copy in all cases because otherwise the programmer looses the portability of his code he would need to test to see if the mes Copyright 1996 Eonic Systems Virtuoso User Manual P1 31 Functional support from Virtuoso 4 7 7 a sage came from a local or remote task and handle the message accord ingly This would complicate hi
444. red behavior can be obtained One or more typical Virtuoso nanokernel service uses List of related Virtuoso nanokernel services that could be examined in con junction with the current Virtuoso nanokernel service Specific notes and technical comments Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 2 19 Alphabetical List of nanokernel entry points 22 1 start_process e BRIEF Initialize and start a nanokernel process CLASS Process management e SYNOPSIS void start_process void stack int stacksize void entry void int i1 int i2 e DESCRIPTION This C function initializes the process control structure of a process and subsequently starts it The entry point the stacksize the initial values for i1 and i2 and some internal variables are written to the PCS This call returns when the started process deschedules or terminates e RETURN VALUE none EXAMPLE In this example two processes using the same code but different parame ters are initialized and started int adc1 100 stack for first process int adc2 100 stack for second process extern void adc_proc void process code extern struct adc_pars ADC_Params 2 parameter structs start_process adc1 100 adc_proc amp ADC_Params 0 0 start_process adc2 100 adc_proc amp ADC_Params 1 0 e SEE ALSO e SPECIAL NOTES This function cannot be used from within a high pr
445. ren nenene 11 1 Warning when using Virtuoso on a PC oo eeeceeceeeee cece eeeeeeeeeee ener eeeeseeeeaaeeeeneeaaeeeteaeaes 11 1 Virtuoso on the Motorola 56K DSP M1 1 Virtuoso versions ON SOK Taidre anae va doashevenes secs AE iA M1 1 DSP 56001 Chip Architecture ecceict gs cescneesndengendaetehaet ides inveteiaxeraedieaeceaudnsetteatce M1 1 DSP56001 software architecture ccccceecsesseeeeesseceeeseaeeeceeeaeeeseeesceseeseeseteeeeesas M1 3 Addressing Modes 2 s t h hes eae ct fs lteter eee eae date M1 5 VO Memory Sekt ao ch Sia wate Garde a cat kale ean che Sat cat ea al e E M1 6 PO PUGA YS woscecteesiant st a one sate a a et acne cients M1 6 PORT Beia ra ceviche eee SRO tei M1 6 PORT IG testes E E E E E E E E N M1 8 EXCOP ONS sorei aira a i a a a a aa E A A e E ti paaa M1 8 Relevant GOCUMENMATION siisii niinniin etan ea aaa Da danke anenai EAEAN aA M1 10 C calling conventions and use of registers ss essesseeesseeeseseeersrersttrrrerrrerrerr nsen M1 10 Storage Allocation fressar tinsi oeio saa e eatea Eg EREE EAEN ENSA E r Aaii M1 10 Register Us g ssoiicnio anria donan aR o pa oaaae Seveadaceatmeeasiie eeteiee Urak E ONTE Piae ee M1 10 Subroutine Linkage ssec eae raea eeaeee e AEEA Ria M1 11 TOC 10 Virtuoso User Manual Copyright 1996 Eonic Systems Preserved Registers sick ieee ieee eee tes eee een ee M1 11 Register Return Values ccceecects nc aetvecdinccieeeateeveedsiens apes teeeceeapeeti
446. required performance He should try to program as much as possible at the microkernel level as this level is fully portable and scalable Lower levels require more assembly provide less flexibility but can provide the time criti cal performance needed for very fast reaction to interrupts Global Interrupts Enabled FIGURE 12 Interrupt servicing an open multi level approach P1 36 Virtuoso User Manual Copyright 1996 Eonic Systems Functional support from Virtuoso 4 9 Levels supported by the Virtuoso products In order to provide an overview following table summarizes what default lev els are supported in each Virtuoso product Nano Micro Classico main yes yes yes microkernel no yes yes nanokernel yes no yes ISRO yes yes yes ISR1 yes no yes Multiple priorities when supported by hardware 4 10 Support for parallel processing Virtuoso comes in three implementations The first one SP has only sup port for single processor system The second one MP adds multiprocessor capabilities by providing low level drivers that permit to communicate between directly connected processors The third implementation VSP enables the user to access the defined objects and their services in a way totally independent of the location of objects in the network That is the ker nel will automatically assure that the kernel service is executed even if the cooperating objects are located on different no
447. returning from the interrupt The first type of ISR requires an interface to the nanokernel and needs to be much more structured It consists of 3 parts Saving a number of registers on the stack What registers and the order in which they need to be saved is fixed m Performing whatever operation that is necessary including the modi fication of the status of one or more kernel objects m Transfer control to the nanokernel which will decide on the next step The list of registers that need saving is called INTSET It contains the follow ing registers in order MODE1 ASTAT rO r1 r2 r4 r8 r12 i4 12 Also see 21 7 8 Register conventions on page 12 The second part of the ISR requires a lot more knowledge of the internals of the nanokernel and microkernel For more information check 21 7 The nanokernel on the 21060 on page 7 Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI2 3 Virtuoso on the ADSP 2106x SHARC 21 6 2 Writing an ISR routine To illustrate here are 2 examples one of each category First example a simple ISR no kernel entry include lt def21060 h gt segment pm seg_pmco global _simple_isr endseg segment dm seg_dmda extern _CountP endseg segment pm seg_pmco _simple_isr dm i7 m7 r0 10 10 dm i7 m7 10 10 _CountP 10 dm mS5 i0 0 r0 l dm m5 i0 r0 10 dm 1 i7 10 10 10 dm 2 i7 modify i7 2 rti endseg
448. riate partitions for the worst case conditions Note that dynamic memory allocation and deallocation is still possible by the use of resource protection P1 28 Virtuoso User Manual Copyright 1996 Eonic Systems Functional support from Virtuoso m MemoryMap1 MemoryMap2 eal Block in use Free Block FIGURE 6 4 7 5 4 7 6 Virtuoso allocates memory in user defined fixed block sizes Class Resource The resource protection calls are needed to assure that access to resources is done in an atomic way Unless the processor provides real physical protec tion the locking and unlocking of a resource is in fact a convention that all tasks using a resource must follow A task can get the exclusive use of a resource by using a KS_LockW service call on it After its use the resource must be released with an KS_Unlock call With this mechanism all critical objects can be protected Class Semaphore Semaphores are used to synchronize handshake between two tasks and or events A signalling task will signal a semaphore while there will be another task waiting on that semaphore to be signalled One can wait on a sema phore with a time out or return from the wait if no semaphore is signaled This can be useful to make sure that the task doesn t get blocked Manual resetting of the semaphore is also possible With v 3 0 counting semaphores are used They permit the concurrent signalling of a semaphore while a
449. rity is used at all times and at all levels in the microkernel and guarantees that all higher prior ity related actions will precede lower priority related actions even if they hap pen later in time A single exception is that once a microkernel service is being served in the microkernel it will continue to run until the microkernel action has finished Note that meanwhile interrupts will still be accepted in the background The different microkernel activities are event driven avoiding any form of active waiting or polling so that a suspended microkernel action will never block the system Heterogeneous processor systems The virtual single processor model is so powerful that Virtuoso even runs on P1 40 Virtuoso User Manual Copyright 1996 Eonic Systems Functional support from Virtuoso systems with mixed types of processors The key point is that the underlay ing mechanism used by the microkernel is message based Therefore to transfer a command packet or data from one processor to another the only requirement is the presence of a fast enough communication port This can be common memory like in VME systems a serial link or a dual port RAM interface A typical example could be a system with several processors depending on the function they have to fulfill For example control I O func tions typically require less powerful processors while compute intensive cal culations can best be run on high speed processors like a
450. river sermien enaa CE A S TR TI 10 Virtuoso on the Texas Instruments TMS320C40 TI2 1 Brief description of the processor architecture cececceceeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeaaees TI2 1 TMS320C40 Chip Architecture ces sc ci cccueritierd essa untavererarnehl nee dashed eeecennens TI2 2 TMS320C40 Software Architecture 0 cccceceeeseeeeceeeeeeeeeeeeeeeeeeeeaeeeeeeeeaeenees TI2 3 TOC 12 Virtuoso User Manual Copyright 1996 Eonic Systems Addressing MOGES xe ate elk tee ate aay eee a aces cash ee Tl2 4 Relevant documentation ie dechee tc wake tidecteietetvediet setae aecetiaei ced teeters TI2 4 Programming in C and assembly sssssnsessseeseernsrirnrrrterttnetrsttrrnntnnnenserrnsee erene TI2 5 Data representation jisisinccceteeeewdekeioutee ie aideaeaeay antec Tl2 5 Big and Small Models go dccacassuseserscotioes kane hoesadtecechinucengeeset ts edeadeesiavedeatemnceatee TI2 5 Parameter passing conventions cceeeeeeeceeceeeeeeeeeseeeeeceeeeenee seseeneeeeneees TI2 5 Memory sections for the C compiler and Virtuoso 00 2 cece teeeeeteeeeeeeteee resene TI2 6 Programming the nanokernel TI2 8 NYO GICTION ipsins ioctl aea E EAER AE EE AARAA A yeas EE AEAEE TA EEEa Tl2 8 Internal data SIRUICEUTES sicucests shaves ses adcat lve ssytedeahwensnpadec ashe censs eouaabhe pi eyenedea veoh odeadeleaes Tl2 9 Process management ay siete ceive cicten sade deiady ctegees aedeagus dade eeerteapedcakbearente Tl2
451. rnel resources tasks semaphores T8 10 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the INMOS T2xx T4xx T8xx queues etc are defined system wide Hence in the whole system each of these resources is uniquely identified For example there is only one task with the highest priority although on each node in the network the task with the highest local priority will be scheduled first by the kernel The main advantage of this system lies in the fact that by making the datastructures more dynamic it has become possible to handle the messages in order of priority of the task that generated it Hence the communication latency is reduced to a minimum Below the key performance figures for Virtuoso are summarized hop delay 50 us task to task throughput rate 1 5 MB s one link to 4 6 MB s 3 links message set up time lt 25 us synchronization delay for two tasks in a cluster of 1000 processors around 600 us kh O N The main conclusion is that small clusters of transputers using Virtuoso act as a single processing unit but with increased performance as compared to the same program running on a single transputer In addition it is now feasi ble to have several high priority tasks running at the same time This is important if several high priority tasks are needed and when timely termina tion is a design criterium 33 12 Using the compiler libraries with Virtuoso The use of a
452. rocessor KS_DequeueW CONIQ char sizeof char Input a character Can be used from a remote processor printl char string K_RES CONRES K_QUEUE CONOQ Output a string ofcharacters For formatting the string use the sprintf function from the stdio library These character based functions are used by the Virtuoso Task Level debug ger when used with a terminal connection While its operation is slower than using std I O it has the advantage that the full stdio lib is not needed This reduces memory requirements as well as permits an easy port when that target is only accessible using a terminal 12 5 0 b Standard I O driver This driver provides standard I O They should not be used with the console drivers as first characters might be lost The following section details the available functions 12 5 0 c Graphics driver This driver implements an emulation of Borland DOS graphics calls The fol lowing section lists the available calls Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 127 Runtime libraries 13 Runtime libraries 13 1 Standard I O functions 13 1 1 Implementation limits These functions provide the same functionality as the equivalent ones pro vided with the runtime library of your compiler Note however that they were adapted to work in conjunction with the multitasking and distributed environ ment of Virtuoso and use the host server program See the manual of the compiler for a descri
453. routines that will put a thing to do into the kernel FIFO These routines are in fact the entry points of the kernel The first two can be called as C functions while the third is just a label to jump to void kernel_task_entry void This is called when a task requests a kernel service A command packet is assembled and the entry point is called with a pointer to the command packet as the parameter see IFACE C for examples The pointer is put into the FIFO and control is given to the kernel This call returns when the call ing task resumes execution the task may have been swapped out in between void kernel_call_entry void This is used to put a new element in the kernel FIFO from within the kernel itself This is the opposite of the previous one it puts the pointer into the FIFO assumes the kernel is already running and returns immediately It is Tl 8 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Texas Instruments TMS320C30 amp C31 used by the timer system and the routing layer to put timed or remote com mand packets into the FIFO kernel_sign_entry This is the entry point for an ISR that wants to hand over an interrupt to the kernel This is done by branching to this entry point from within the ISR When the jump is performed it is assumed that the ISR return address anda small implementation defined subset of CPU registers are still pushed on the stack of the interr
454. rrent owner Virtuoso will look for the next waiter in the list If there is one it will become owner of the resource In practice it is possible that situations arise in which resources are locked by lower priority tasks while a higher priority task that wants to lock on it is kept in the waiting list Tasks of intermediate priority can then get hold of the CPU and preempt the lower priority task The result is that the higher priority task can be kept for quite a long time from running even while the resource it is waiting for is not used The solution is then to raise temporarily the priority of the lower priority task This algorithm is called the priority inheritance algorithm A variant of this algorithm is planned to be available in a later version of Virtuoso In the current version the programmer can achieve the same result by raising the priority of the using task prior to the resource lock He must not forget to reset the priority afterwards Timers In the descriptions of time based functions to follow it will be important to understand the conventions used by Virtuoso All timers in Virtuoso are either 16 bit or 32 bit values depending on the processor size The two time units used internally by Virtuoso are ticks mostly maintained by a low resolution clock driver and the value of the high resolution timer hardware if any present A tick gives the amount of time between clock generated system interrupts or equivalently the period
455. rrupt handler will then typically fill up a buffer and transfer control to a waiting task often the driver associated with the hardware that generated the interrupt Note than when the ISR is very short it is better to execute everything at the ISRO level because the transition to the ISR1 level requires a few processor cycles Also consider that some processors have up to 32 priority levels with interrupt capability for handling interrupts This basically means that one Copyright 1996 Eonic Systems Virtuoso User Manual P1 35 Functional support from Virtuoso disposes of ISRO up to ISR32 to handle interrupts Instead of using an ISR1 the interrupt can be handled using a nanokernel process This has the low register requirements of an ISR but the program mer has additional services available that permit him to build up the interrupt handling using other processes as a true multi tasking program This is very useful for fast interrupt driven drivers For example the interprocessor com munication drivers of Virtuoso are written as nanokernel processes At the end but not necessary so the ISR1 or the process can signal an event on which a normal task is waiting to further process the interrupt at the C level An important point to note is that Virtuoso does not impose any use of a cer tain level to address the application requirements As the diagram below illustrates the user can choose any combination of levels to achieve the
456. rrupt service routine include lt def21020 h gt include lt macro h gt macro s for nanokernel segment pm seg_pmco global _rxhost_irgh endseg segment dm seg_dmda var HOST_EVENT 8 extern _K_ArgsP channel for the kernel endseg segment pm seg_pmco Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 17 Virtuoso on the Analog Devices 21020 DSP _rxhost_irgh registers that MUST be saved by the IRQ dm i7 m7 MODE1 dm i7 m7 ASTAT dm i7 m7 r0 dm i7 m7 r1 dm i7 m7 r2 dm i7 m7 r4 dm i7 m7 r8 dm i7 m7 r12 r4 i4 dm i7 m7 r4 dm i7 m7 i12 registers that MUST be saved by the IRQ i4 dm _K_ArgsP r2 dm HOST_EVENT PRHI_PSH pushes event on kernel channel ENDISR1 ends the interrupt routine endseg For more information see also the chapter upon the nanokernel 18 9 3 Alphabetical list of ISR related services 1 _kernel_sign_entry entering the kernel from within an ISR 2 KS_EventW int IRQ waits on an interrupt at the task level 3 KS_EnablelSR int IRQ void ISR void installs the ISR 4 KS_DisablelSR int IRQ disables the ISR See part 2 for details 18 10 The nanokernel on the 21020 18 10 1 Introduction The nanokernel provides the lowest level of functionality in the Virtuoso sys tem It is designed to perform
457. rs have to be saved However for a signalling ISR it is not advised to make a subroutine jump to a C function from within the ISR as this would introduce needless overhead of context saving The kernel when jumped to by label Fkernel_sign_entry will perform a context save for all non preserved registers In this case it is advised to make a task that waits on an event with kernel service KS_EventW n and that calls this C function after it is waked up by a signal to event number n Interrupt disabling times For the release of Virtuoso for the DSP96002 processor it is not needed to disable interrupts in the code of an ISR Because it is advised to disable interrupts in a period as short as possible no interrupt disabling should be done in an ISR There are however certain sections in the kernel code where interrupts must be disabled because these sections are critical and may not be inter rupted The longest period in the kernel code that interrupts are disabled is 52 29 wp 7 wy clock cycles Copyright 1996 Eonic Systems Virtuoso Binding Manual M3 17 Virtuoso on the Motorola 96K DSP whereby wp and wy are the memory wait states for external program and Y data memory respectively Taking a clock frequency of 33 MHz and zero wait state external memory into account the longest interrupt disabling time in the kernel is 52 clock cycles or 1 58 microseconds M3 18 Virtuoso Binding Manual Copyright 1996 Eoni
458. rsions on 56K Virtuoso Micro SP is available for the 56K A port of the nanokernel on 56K is available in a single processor version Virtuoso Nano SP 27 2 DSP 56001 Chip Architecture This section contains a brief description of the DSP5600x processor architec ture It is not intended to be a replacement of the Processor s User Manual but as a quick lookup for the application programmer Detailed information can be found in the DSP56000 DSP 56001 User s Manual from Motorola The DSP56001 has a Harvard architecture Separated program and data addressing with multiple internal buses Interfacing to the outside world is done via one 47 pin expansion port port A and 24 additional I O pins which are divided between ports B and C Of the 24 pins 15 are assigned to port B These pins can be used as general pur pose I O pins or as host MPU DMA interface pins Port C consists of 9 pins also usable as general I O pins or as SCI Serial Communications Interface and SSI Synchronous Serial Interface pins The heart of the processor consists of 3 execution units operating in parallel the data arithmetic logic unit ALU the address generation unit AGU and the program controller In addition to these 3 execution units the 56K has also six on chip memories three on chip MCU style peripherals SCI SSI host interface a clock generator and seven buses The main components of the DSP56001 are Data and Address Buses Data A
459. rtuoso microkernel services 11 13 e SUMMARY e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES KS DisablelSR Disable interrupt service routine Driver service void KS_DisableISR int IRQ The KS_DisablelSR microkernel service disables the specified interrupt rou tine and removes the corresponding ISR from the interrupt handler table As a result all subsequent interrupts from that source are ignored None KS_DisableISR 4 printf Interrupt 4 now disabled KS_EnablelSR KS _EventW This service does not actually enter the microkernel and therefore cannot cause a task switch Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 39 Alphabetical List of Virtuoso microkernel services 11 14 e SUMMARY e CLASS es es eae e SYNOPSIS e DESCRIPTION e RETURN VALUE KS Elapse Compute elapsed time Timer K_TICKS KS_Elapse K_TICKS reftime The KS_Elapse microkernel service returns the elapsed time between two or more events To get the elapsed time one issues two calls The first one is required to set the beginning time and the returned value should be dis carded The second and each subsequent call returns the number of clock ticks between the previous time marker and the current system low timer Elapsed time in system ticks EXAMPLE K_TICKS timestamp diffl
460. rtuoso on the Analog Devices 21020 DSP If it does the initial value can always be reloaded from NANOK_PRHI 10 must point to the PCS whenever the process calls a nanokernel service and when it terminates The Nswap register set is always available but note the special use of i0 If a PRHI process is swapped in as the result of a C function call by the PRLO process then the Cfree set is available for use by the PRHI process This means that the process can safely call any C function It should of course save those registers in Cfree that it wants to preserve across the call If a PRHI process is swapped in as the result of an interrupt handler calling an ENDISR service then the INTSET registers are available to the PRHI process Before calling a C function the process must save the set Cfree int set and it must restore the same registers before it is swapped out this is always possible since a PRHI process is never preempted 18 10 9 Interrupt handling In the Virtuoso system model interrupt handlers are the interface between asynchronous events and the processes that are waiting for then To be use ful most interrupt handlers will have to interact with the rest of the system at some time Using flags to be polled by the foreground process is usually not an acceptable practice in a real time system This method introduces a superloop structure into the application with all its inherent problems In a system using
461. rtuoso on the Motorola 96K DSP ER and an 8 bit Condition Code register CCR Special attention is given here to the Interrupt Mask bits 11 and 10 in the Mode register MR These bits reflect the current priority level of the processor and indicate the interrupt priority level IPL needed for an interrupt source to interrupt the processor The current priority level of the processor may be changed under software control The interrupt mask bits are set during processor reset 31 0 31 23 145 7 0 31 7 0 PC MR IER ER CCR OMR 31 0 31 0 LA LC 31 031 0 i 31 5 0 SYSTEM STACK 4 SP SS 15 FIGURE 17 FIGURE 18 DSP96002 Programming Model Program Controller The Loop Counter LC is a 32 bit special purpose register used to specify the number of times a hardware program loop is to be repeated The Loop Address Register LA is a 32 bit register that indicates the location of the last instruction word in a hardware program loop The System Stack is a separate internal memory which stores the PC and SR for subroutine calls and long interrupts The stack will also store the LC and LA registers in addition to the PC and SR registers for program looping The System Stack memory is 64 bits wide and 15 locations deep The Stack Pointer SP is a 32 bit register that indicates the location of the top of the system stack and the
462. ruction e RETURN VALUE NONE EXAMPLE KS_DisableISR 9 SEEALSO KS_EnablelSR e SPECIAL NOTES M1 20 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Motorola 56K DSP 27 7 3 BRIER sayy Seta SYNOPSYS e DESCRIPTION e RETURN VALUE EXAMPLE KS EnablelSR Enables an ISR to be triggered by an interrupt void KS_EnableISR int IRQ void ISR void int PrioLevel int Mode This C callable kernel service installs an ISR by writing a JSR instruction at the appropriate place in the interrupt vector table and setting the IPR register of the processor with the correct bit values for the actual interrupt This ser vice may be used to install following interrupts together with their priority level and interrupt mode if appropriate a IRQA a IRQB Host Command Other interrupts can also be installed by this service but for them the priority level and interrupt mode is not applicable and the arguments PrioLevel and Mode are not used NONE extern void ISRDMACh1 void KS_EnableISR 9 ISRDMACh1 2 0 Copyright 1996 Eonic Systems Virtuoso Binding Manual M1 21 Virtuoso on the Motorola 56K DSP 27 7 4 e BRIEF ee ee ee e SYNOPSIS e DESCRIPTION e EXAMPLE SEEALSO e SPECIAL NOTES KS EventW Waits for event associated with ISR KS_EventW int I
463. rupt handler calling an ENDISR service then the INTSET registers are available to the PRHI process Before calling a C function the process must save the set CFREE Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 2 13 Virtuoso on the ADSP 2106x SHARC 21 7 9 INTSET and it must restore the same registers before it is swapped out this is always possible since a PRHI process is never preempted Interrupt handling In the Virtuoso system model interrupt handlers are the interface between asynchronous events and the processes that are waiting for them To be useful most interrupt handlers will have to interact with the rest of the sys tem at some time Using flags to be polled by the foreground process is usually not an acceptable practice in a real time system This method intro duces a superloop structure into the application with all its inherent prob lems In a system using the nanokernel interrupt handlers can communicate with processes using the same channel operations that are available to pro cesses However there are some restrictions In contrast to a process an interrupt service routine does not have a private workspace it executes on the stack of whatever process was interrupted An ISR on the 21060 can be interrupted by an ISR of higher priority So any number of interrupt handlers can be piled on top of each other on the same stack owned by the current process This has some importan
464. ry a device a non reentrant code section or whatever A typical resource is the server interface to a host All that is necessary for any such resource needing protection is to be identified and given a name It is the responsibility of the programmer to provide such identification The P2 8 Virtuoso Reference Manual Copyright 1996 Eonic Systems Virtuoso microkernel types amp data structures 7 7 programmer must insure that any use of the resource be preceded by a Virtuoso microkernel service that locks out other users Correspondingly when the task has finished using the resource the Virtuoso function to unlock the resource must follow With these two simple functions KS_Lock and KS_Unlock Virtuoso can protect a resource and at the same time arbitrate which task is to get subsequent control when the critical period has passed Note that it is still the programmers responsibility that the resource is correctly used As such the logical resource is merely a flag If bypassed you will get cases in which your physical resource is no longer protected When a task locks an idle not being used resource Virtuoso sets the current owner to the requesting task Another task trying to lock the same resource will then find the resource already in use Virtuoso places the second task into a resource wait list and the task is inserted into the wait list of the resource in order of its priority When the resource is unlocked by its cu
465. ry or via the event pin 2 Because it has to wait on a timer event 3 Because of an interrupt from a high priority process which is ready to exe cute 4 Because its timeslice has expired and a descheduling point has been reached In both queues all processes are executed in the order they were when placed in the queue Parallel processing on a single transputer is then emu lated through the time slicing mechanism Note that not all processes are present in the queue at all times Only those processes that are ready to exe cute will be Hence to completely know the state of an executable process on the trans puter one needs to know the following elements 2 Wptr Iptr Areg Breg Creg Ereg and the process status if appropriate FAreg FBreg FCreg the place in the queue Fortunately these elements can be known by exploiting the fact that when a low priority process is interrupted by a high priority process its elements are saved in the lower memory locations Once these elements are known it is possible to rearrange the linked list of the process queue such that using a look up table the highest priority process is always in front of the queue Care has to be taken that the linked list structure is not broken at any moment especially as the transputer may start to manipulate the queue independently of the currently executing instruction 8 The final result is the capability of preemptive scheduling meaning tha
466. ry point Calling _start_process stack starts the process As the caller is the PRLO process there can be no other PRHI process and the new process will start execution immediately Control returns to the caller when the new process terminates or deschedules by waiting on a channel The first time a PRHI process is swapped in it continues from its entry point The stack pointer will point to the PR_PEND field in the PCS A process ter minates by returning to the address in this field The code at NANOK_TRMP invokes the nanokernel swapper to switch to the next process To restart a terminated process repeat the calls to _init_process and _start _process When a PRHI process is swapped in i0 points to the start of the PCS A pro cess can create local variables by incrementing the initial stack pointer by the number of words required Note On the 21020 the stacksize is also a parameter This is because of the fact that the stackpointer is moving from the top to the bottom of the stack Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 21 Virtuoso on the Analog Devices 21020 DSP 18 10 4 Nanokernel communications A channel type is defined by a data structure and a number of nanokernel services that operate on it Each instance of the data structure is called a channel Channels provide both porcess synchronization and data communi cation The nanokernel does not itself use or create channels However the ser
467. s 38 11 BRIEF prrs e CLASS 2 Saw es e SYNOPSIS e DESCRIPTION e ENTRY CONDITIONS e EXIT CONDITIONS EXAMPLE SEEALSO e SPECIAL NOTES PRHI_POPW Remove next element from a stack channel or deschedule Process communication LATcond PRHI_POPW PRHI_POPW is defined in TRAPS INC If the stack is not empty the top element is removed and returned to the caller If the stack is empty the calling process is swapped out and set to wait on the channel It will be rescheduled by the next call to the PRHI_PSH ser vice on the same channel AR1 pointer to stack channel struct AR3 pointer to PCS of calling process AR4 element removed from the stack RO AR1 AR2 R11 and ST are corrupted D include traps inc assume AR5 points to a parameter struct obtain element at top of stack lat PRHI_POPW ldi ar5 INPUT_CHAN arl nop nop use stack element in AR4 PRHI_POP PRHI_PSH This service must not be called from the low priority context or by an isr Copyright 1996 Eonic Systems Virtuoso Binding Manual TI2 35 Alphabetical List of nanokernel entry points 38 12 e BRIEF scape Secs e GLASS eae ea e SYNOPSIS e DESCRIPTION e ENTRY CONDITIONS e EXIT CONDITIONS EXAMPLE SEEALSO e SPECIAL NOTES PRHI_PUT Add a packet to a linked list channel Process communication LATcond PRHIL_ PUT PRHI_PUT is def
468. s Glossary Abort task API Class Debugger Driver Event FIFO Group Hard Real time High Precision Timer Interrupt ISR Level programming Link To halt a task s execution and put it in a state where it can be started A task in a waiting state should not be aborted Application Programming Interface A category of microkernel service The task level debugger used to inspect the state of microkernel objects Not to be confused with the source level debugger or emulator Low level code used to interface to peripheral hardware Often implemented using interrupt handlers and nanokernel processes A synchronization signalled by an interrupt han dler or nanokernel process to a waiting micro kernel task Queue A collection tasks A system subject to detailed and rigid timing constraints A clock that can be read with higher resolution than the microkernel timer often provided by hardware An asynchronous event triggered by hardware outside the CPU to which the processor has to respond Interrupt Service Routine Code to respond to an interrupt An application programming interface API Lower levels offer reduced functionality and smaller overheads Communication medium between processors e g Comport on the C40 Copyright 1996 Eonic Systems Virtuoso User Manual GLO 1 Mailbox Memory Message Microkernel Move Data MP Nanokernel Node Obj
469. s More on this later 28 3 Configuration of the processor boards CC 112 of CompControl In order to use the capabilities of the CC 112 processor boards for applica tions with the Virtuoso kernel following configuration is needed On the main processor board running the server program and the OS 9 ker nel Copyright 1996 Eonic Systems Virtuoso Binding Manual M2 3 Virtuoso on the Motorola 68030 systems Oro NED OTA Ou NS N N N ND YO YP NYY ND A O N Oo RAON BH OK DAN OO A ON CO watchdog jumper disabled connected EPROM jumpers configured for 1 Mbit EPROM SCSI jumper connected cache jumper disabled connected Boot ROM initialization parameters Processor Module Name CC112 Display NVDev contents on Reset Poweron y Boot from floppy disk SCSI port y Boot from hard disk SCSI port y Boot from EPROM n Boot from VMEnet port n Host SCSI ID 7 Hard disk controller SCSI ID 0 Floppy disk controller SCSI ID 1 Reset SCSlbus on Reset PowerOn y Reset VMEbus on Reset PowerOn y DPR Supervisory Access y DPR Non privileged Access y DPR Extended Access y DPR Standard Access y VMEbus DPR Base Address 08000000 Bus Request Level 3 Bus Request Release Mode Request Direct Release On Request Interrupt Handler VMEbus mask Level s 7 6 5 4 3 2 1 enabled Interrupt Handler Local mask Level s 7 1 enabled VMEnet por
470. s Most nanokernel services are assembly routines As parameters are passed using registers no general syntax can be provided as it is processor dependent As they start up and terminate in assembly a good know how of the target processor is required In addition as registers are used to pass parameters be very careful when programing at this level Refer to part 3 of the manual for the details In Virtuoso Nano a more complete nanokernel is used Refer to its manual for details Process management Note The actual syntax might be different depending on the target processor as they depend on the registers and instructions available The descriptions below are therefore generic while the binding manual provides processor specific descriptions init_process void workspace void entry void int paraml int param2 Sets up a nanokernel process C function called from microkernel or main level start_process void workspace Starts up a nanokernel process C function called from microkernel or main level nanok_yield Yield CPU to another nanokernel process Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 23 Nanokernel services 10 2 ISR management end_isr0 Terminates a level end_isrl Terminates a level set_isrl 0 ISR 1 ISR Switch to ISR level 1 10 3 Semaphore based services prhi_sig Signal and
471. s Gorcetaande ands peeatieuviencesatnnbeeeediee M2 1 Building an application executable cccccececeeeeeeceeeceeeeeeeeeseeeeseeeeeeeeeenseeeeeaneeens M2 2 Configuration of the processor boards CC 112 of CompConntrol eceeee M2 3 Additional information about the modules 00 ceeeeeeeeeeeeeeceeeeeeeeeeeeeeeeeeeeeeeee tenets M2 5 Server program for CompControl VME system board running on OS 9 M2 9 Purpose of the Server program 0 cess ceceeeeeececeeeeeeeceeeeeeeeceseeeeeeeeteaeee seen M2 10 Source files for the server program n s eccceeeeeeceeeeeeeeeeeeeeeaaeeeeeeaeeeeneae anes M2 10 Use of THE server program sess ceded ietecs hes fevedete tee dee eee M2 11 Virtuoso on the Motorola 96K DSP M3 1 Virtuoso versions on 96K as2 2 serccaseeheettashbiedt acelosetach Seaeiadt aa teetheeitad cand tenantecenune M3 1 DSP 96002 chip architecture ache ct accteederacetaces Weve fact ecenadexsceutec areca ua auectensnbeeienlees aves M3 1 DSP 96002 software architecture cccccecceceeeeeceeeeeeeceeeeeeneeeeeaeeeeeeeseeeeeaeeaeeeens M3 3 DSP 96002 addressing modes cseticnteicenncs sueiiute dade ectbeencdy anccastovunty cause ercevedes M3 7 VO memory and special registers 0 2 ceeeeeeeeeseeeeeeeeeeeeeeeeeeeeeeeeeaaeeeeaeaaeeee M3 8 Exp sion POMS CONTON aiiin inert Gouge a e eee a M3 8 EEX CGP TONS EA EE E EE E E eae dace M3 8 Relevant documentation ssssssssssssssrresrre
472. s Manual for full details Address Generation Unit vA Ext j pe Ext Addr lt y I Addr gt Switch gt Switch Miy DMA Controller Internal Memory Host X data 512x32 Host Interf lt Y data 512x32 Interf Switch amp Prgm 1024x382 Bit manip gt Ext Vy gt Data lt gt i A gaa y YY f OnE n Clock Program controller DATA Debug Gen ALU Contr FIGURE 16 DS96002 simplified Block Diagram The major components of the DATA ALU unit are Data ALU Register File Multiply Unit Adder Unit Logic Unit Format Converter Divide and Square Root Unit Controller and Arbitrator The Adder Unit has also a Barrel Shifter The major components of the M3 2 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Motorola 96K DSP Address Generation Unit AGU are Address Register Files Offset Register Files Modifier Register Files Temporary Address Registers Modulo Arithmetic Units Address Output Multiplexers 29 3 DSP 96002 software architecture The programmer can view the DSP 96002 architecture as 3 execution units operating in parallel The 3 execution units are the a Data ALU a Address Generation Unit Program Controller The DSP 96002 instruction set has been designed to allow flexible control of t
473. s are the tasks as these are the originators of all microkernel services Each task has a dynamic priority and is implemented as a C function Tasks coordinate using three types of objects semaphores mailboxes and FIFO queues Semaphores are signalled by a task following a certain event that has happened while other tasks can wait on a semaphore to be sig nalled To pass data from one task to another the sending task can emit the data using a FIFO queue or use the more flexible mailboxes While the first type provides for buffered communication mailboxes always provide a syn chronized service and permit the transfer of variable size data Filtering can be performed on the desired sending or receiving task the type of message and the size Further services available with Virtuoso are the protection of resources and the allocation of memory The microkernel also uses timers to permit tasks to call a microkernel service with a time out Depending on the processor type some microkernel calls also provide access directly to com munication hardware and high precision timers The latter is used to directly measure the CPU workload Finally the C programmer disposes of a stan dard 1 O graphics and runtime library of which some of the functions are executed as remote procedure calls by a server program on a host machine 3 2 3 The object as the unit of distribution In a traditional single processor real time kernel objects are identified most
474. s code too much while he would make a copy in most cases anyway So if he only wants to pass a pointer because he knows beforehand that he is on the same processor he will need to pass that pointer explicitly For this reason the header contains a 32bit Info field Once only synchronization the KS_MoveData service The message mechanism is a very secure and flexible mechanism because it synchronizes between sender and receiver before the receiver determines the actual datatransfer In repetitive situations the synchronization and its associated overhead can be eliminated using the KS_MoveData service This service requires that all elements of the datatransfer have been fixed once beforehand As an example consider an image generating task that copies the resulting image always to the same address in video memory The service can be invoked from anywhere in the system and will copy the data for a given size from a source pointer on a given node to a destination pointer on a node When both pointers reside on the same processor the operation is performed using a straight memcopy KS_MoveData Processor B A can be B Processor A FIGURE 9 4 7 8 The KS_Move Data acts like a distributed memory copy operation Class Queue Queues are also used to transfer data or whatever the data represents from any task to any other task but here the data is actually transferred in a buffered and time ordered way T
475. s not saved for leaf subroutines Local data space The location of C variables that have a lifetime that extends only as long as the subroutine is active and that could not be explicitly promoted to register storage class by the optimiser Register spill and compiler temporary space This area is utilised by the compiler to store intermediate results and preserve registers Note The frame pointer RO points to the first element in the local data space Note 2 The stack pointer R6 points to the next available data mem ory location By default global and static data elements are located below the run time stack and each element is referenced by a unique label that is known at com pile time Interrupt Service Routines ISR The two ISR levels that are normally supported by Virtuoso ISRO and ISR1 are not present in the version for the DSP56000 processor since the DSP56000 supports multiple interrupt levels on its own For more details on the different interrupts supported by the DSP56000 see section 27 3 3 of this manual or even more in detail the DSP56000 User s Guide from Motor ola ISR Conventions When using self written ISRs in conjunction with the Virtuoso kernel there are certain conventions to follow a Registers that must be preserved in an ISR a Interrupts that must be disabled at certain sections in the ISR code Saving or preserving registers M1 14 Virtuoso Binding Manual Copyright 1996 Eonic
476. s set EXAMPLE include macro h i4 dm CHANNEL PRHI_POP SEEALSO PRHI_POPW PRHI_PSH e SPECIAL NOTES This service must not be called from the low priority context Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 2 27 Alphabetical List of nanokernel entry points 22 9 PRHI_POPW e BRIEF Remove next element from a stack channel or deschedule e CLASS Process communication e SYNOPSIS PRHI_POPW PRHI_POPW is defined in macro h e DESCRIPTION If the stack is not empty the top element is removed and returned to the caller If the stack is empty the calling process is swapped out and set to wait for the channel It will be rescheduled by the next call to the PRHI_PSH service on the same channel e ENTRY CONDITIONS i4 pointer to stack channel struct i3 pointer to PCS of calling process e EXIT CONDITIONS i1 element removed from the stack rO r1 r2 r8 ASTAT i4 are corrupted EXAMPLE include macro h i4 dm CHANNEL PRHI_POPW SEEALSO PRHI_POP PRHI_PSH e SPECIAL NOTES This service must not be called from the low priority context or by an isr ADI 2 28 Virtuoso Binding Manual Copyright 1996 Eonic Systems Alphabetical List of nanokernel entry points 22 10 PRHI_ PUT BRIEF os ake Add a packet to a linked list channel e CLASS Process communication e SYNOPSIS PRHI_PUT PRHI_PUT is defined
477. s sodomataadeaceawsaemaneucdorten T8 9 Single processor version v 3 0 cad ece cated Raceline meted T8 9 The distributed version cccccccssccececceceeceeeaeeececeeceaeeececeaeeeeeceeceeceeeeesaeeeeees T8 10 Using the compiler libraries with VirtUOSO eee ceeeeeee eee eeeeeee eee eeeeeeeeeenaeeeaeeeeneae T8 11 Specific Parallel C routines not to be used by the tasks ceeeeeeeeeeeeeeeeeeeeeees T8 11 Specific routines of the INMOS C Toolset not to be used by the tasks T8 12 Specific routines of the Logical Systems compiler not to be used by the tasks T8 14 Virtuoso on the INMOS T9000 transputer T9 1 Virtuoso on the Texas Instruments TMS320C30 amp C31 T 1 Virtuoso versions ON TMS320C30 C31 oe cceeecceeeeeeeeeeeeeeeeeseeaaeeeeaeaeeeeseeeaeeeeaaees TI1 1 TMS320C30 Chip Architecture cc cceecceeceeseeeeeeeeeeeee ea aeeeeeeeaaeeesaaeneeeeneesaneenaees Tl1 2 TMS320C30 Software Architecture s ccleteteneettdectoiasei died atect sont nieh nt Goi dehenteteier tees Tl1 3 Addr ssing Modes sentiria eaten a a ea aae aae edadea TI1 4 Relevant GOCUMENATION sioria a A aa TI 4 Application development hints 22 ccceeeeeeseeceee ce eeeeeee eeeeeeeeeeeeeeseeeeaeeeeeeneeenseeeees TI1 4 Interrupt handlers and device drivers for Virtuoso on the TMS32003x 005 TI1 7 Interrupt handling in VirtUOSO seceisadetes an vetaeed eteeui stance tie geen lee ee deserts TI1 7 Parts Of a device d
478. s supported in microcode Four high speed communication links also enable to spread very easily pro cesses over different processors for more performance In a nutshell the transputer is a fast single chip computer with networking and parallel processing capabilities requiring very simple interface logic to the outside world Using the transputer is using computers as components Process control with transputers The transputer as a virtual occam machine exhibits very well the CSP model on which its design was based This CSP model is often found in the archi tecture of process control applications As a result the transputer has intrin sic features making it an attractive building block for process control applications especially if these are distributed If no hard real time constraints are to be satisfied the overhead due to the use of communicating processes is relatively low as the transputer provides support in microcode for process scheduling and for communication If how ever hard real time constraints are to be satisfied the designer is faced with a major difficulty since the microcoded scheduler is a FIFO scheduler Whereas this scheme was chosen for simplicity and performance in terms of throughput a FIFO scheduler cannot guarantee the scheduling of a process within a known time interval With the FIFO scheduler a process can be worst case delayed for a time interval equal to 2 N 2 TS TSCH TS being the timeslice
479. s what Virtuoso delivers The virtual processor model was obtained by using a system wide unique naming scheme All microkernel related objects are defined system wide including the tasks and their priorities semaphores queues mailboxes and resources Hence for the programmer it is as if he is using a processor clus ter as a single real time processing unit The tricky thing is that the Virtuoso microkernel does more than correctly scheduling the tasks as is done in the single processor version Its operation is as follows First for each microkernel service the microkernel verifies whether the requested resource or service is available locally or on some other proces sor If it is locally available it is handled the same way as a single processor Copyright 1996 Eonic Systems Virtuoso User Manual P1 39 Functional support from Virtuoso 4 15 kernel would do If it is not locally available the microkernel service request is transformed into a remote command packet This command packet is composed of a header and a body The header contains the type of micro kernel service and its parameters while the body contains the actual data to be transferred if any As such some microkernel commands contain no body at all as they simply transfer a microkernel service from one processor to another example the KS_Start call To achieve this kind of topology transparency the microkernel has been extended with an embedded r
480. s where characters are stored one per word or where sizeof does not return the number of 8 bit bytes in a type Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 75 Alphabetical List of Virtuoso microkernel services 11 42 e SUMMARY e CLASS es es e SYNOPSIS e DESCRIPTION e RETURN VALUE e EXAMPLE SEEALSO KS ReceiveData Get the message data Mailbox void KS_ReceiveData K_MSG msgstruc The KS_ReceiveData microkernel service is used to retrieve the message data that belongs to the previously received message The message data is copied to the destination address provided by the receiving task and the sending task is rescheduled If the size member of the message structure is set to zero only the latter action is performed NONE K_MSG msg K_MBOX MBOX1 char data 256 msg size 9999999 msg tx_task ANYTASK msg rx_data data KS_ReceiveW MBOX1 amp msg if msg size gt 256 printf message too large n msg size 0 KS_ReceiveData amp msqg KS _ Send KS SendW KS SendWT KS _ Receive KS ReceiveW P2 76 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services KS_ReceiveWT e SPECIAL NOTES The size member is the number of 8 bit bytes in the message Care needs to be taken when specifying sizes on systems where characters are stored one per word or where sizeof do
481. sdef system definition file format The system definition file can be made with any text editor Many of the kernel objects are known to the kernel by an identifier This is generally an integer e g a 32 bit word The higher bits represent the node identifier while the lower bits represent the object identifier The identifiers are automatically assigned by Sysgen and must be unique in the system Therefore when adding or deleting an object make sure that Sysgen is invoked so that all include files are regenerated Sysgen will require the entry of names for the various system objects All names follow a standard naming convention A name is a maximum of 10 characters if you need more Sysgen can be adapted the first of which must be alphabetic No embedded spaces are allowed while upper and lower case can be used A name must be unique All attributes of an object are numbers Note that the system definition file syntax follows some con ventions of C As a result you can define numbers as symbolic names use include files and use comments Entries must be separated by one or more spaces and must start with a keyword followed by the symbolic name and the attributes Note that some definitions and configuration data must be specified in the main c file Note that on single processor versions or versions that support only one type of processor some of the entries need not to be defined as these are known by default As such there are no n
482. se portions onto the two ports A and B Expansion ports control The DSP 96002 has two external expansion ports Port A and Port B Each port has a bus control register BCRA and BCRB where memory wait states may be specified BCRA and BCRB are located on addresses X FFFFFFFE and X FFFFFFFD respectively Exceptions Exceptions and interrupts are prioritized a higher priority interrupt can sus pend the execution of the interrupt service routine of a lower priority inter M3 8 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Motorola 96K DSP rupt The priority level of an interrupt can be programmed to be at level 0 1 2 or to be disabled Level 3 has the highest priority level and is unmaskable This level is used by the RESET interrupt and by several exceptions like Stack Error Illegal Instruction and F TRAPcc Each interrupt or exception starts at its own vector address Following is a list of all interrupts and their starting address Starting Address Interrupt Source FFFFFFFE Hardware RESET 00000000 Hardware RESET 00000002 Stack Error 00000004 Illegal Instruction 00000006 F TRAPcc 00000008 IRQA 0000000A IRQB 0000000C IRQC 0000000E Reserved 00000010 DMA Channel 1 00000012 DMA Channel 2 00000014 Reserved 0000001A Reserved 0000001C Host Interrupts 0000003E Host Interrupts 00000040 Reserved 000000FE Reserved 00000100 User Interrupt Vector 000001FE User Interrupt Ve
483. se with its employees contractors subcontractors agents or any other person or organization under Customer s control and having access to the Licensed Product to sat isfy Customer s obligations under this Agreement with respect to the use copying protection and security of the Licensed Product 5 5 Pay to Eonic Systems a runtime license fee for every processor or com puter system executing any instance of the licensed product be it as OBJECT CODE and indistinguishable from the EXECUTABLE CODE as far as the payment of said runtime license fees is not covered by any other agreement between Eonic Systems and CUSTOMER 6 CUSTOMER PROHIBITIONS Regarding the Licensed Product the Customer shall not 6 1 Permit any person or persons under its control to compromise the exclu siveness of the Licensed Product and the rights of Eonic Systems under the law of this Agreement 6 2 Provide or otherwise make available to another party any SOURCE CODE or OBJECT CODE or documentation which forms part of the Licensed Product whether modified or unmodified or merged with one or more other works 6 3 Use the benefits of the Licensed Product to engage in the development of a product or products having the equivalent functional specification or serving the same purpose as the Licensed Product so as to be in direct com petition with the Licensed Product Copyright 1996 Eonic Systems Virtuoso User Manual LIC 3 License agreement 7
484. sed as a return value for the server program This macro will terminate the host server and return 0 zero to the envi ronment of the server program int server_getarg int argnum char buffer int buflen It can be used for reading arguments following the network filename on the host program commandline The function returns nonzero if the argument is present and zero otherwise Argument 0 is the NLI file name int server_getenv int srce char dest int len It can be used for reading arguments following the network filename on the host program commandline The function returns nonzero if the argument is present and zero otherwise Argument 0 is the NLI file name Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 125 Hostserver and netloader 12 5 void call_server void This function transfer the contents of the TXDATA memory area to the hostserver and returns when the reply has been written in RXDATA void server_system char comm This function will execute the command pointed to by the parameter in text format in the environment of the host program and return the value of that system call void server_putchar int c This function requests the host server to put a character on the host server screen void server_putstring char s This function requests the host server to put the string that is pointed to by the parameter on the host server screen int server_pollesc void i
485. sessesseeseesorestrrnnntnnnrnrnnn Senrges oaag erent M3 10 C calling conventions and use of registers ceeeeeeceeeeeeeeeeeeee eee eeeeeeeeeeeeenaeeeeee M3 10 Storag amp Allocation sis a a te a e a aa a a M3 10 Segmentation model oe fo sale cede ad sas wendeeceny ca ca lense ves geraeubaaedeaceagecdearnatataaacescets M3 10 Register usage ssisisnar errire irna noraino Eana eA E EEEE SANESA ENANA mae devia ene M3 11 Subroutine linkage aus cs cineca ds Senco foal hes Deeb Se edited nt etan ed acevo ceeabies M3 11 Stack AV OUI ec Peete E E steele eerie M3 13 Interrupt Service Routines ISR ecccceeceesseeeeeeeeceee eeeeeeeeaeaeeeenaeaaeeseeeeeaaeeeeaeaaees M3 15 ISR conventions seee merai aa R apeadec a EERE AEE dg ae RRES Ei M3 15 Alphabetical list of ISR related services ccecceeeecesceeeeeeceeeeeeeeeeeeeeeeeceseeaeeeeeees M3 19 Hl area elule lt 2 E E E Osere tne Miner em teerrar ner tiie ttre T M3 22 Developing ISR TOUtINES isisisi a a a ed eames tend AEE M3 24 Copyright 1996 Eonic Systems Virtuoso User Manual TOC 11 The nanokernel on the 96002 oon eee ceececeeesececeeeeeceeeeeneenseeeceecseeecaneaeeenneeesenenss M3 24 Predefined AFVEE e Qa tentansies a Mavaivinstaevaduislaiedelaveatelaatelss M3 24 The timer device driver ooo cece cessceececaceeceecaececeeecaneececeeceececeesceeeeeeeeseaeeees M3 25 The host interface device driver eesseesssseresseerrrerrrnsrrsrentr
486. ssor monitoring tasks check the operational status of the proces sor When a failure is detected the tasks on the erroneous processor are considered as terminated while the backup tasks are made executable As the location of queues semaphores mailboxes and resources is not visible to the application task it is fairly straightforward to write them in such a way that the system continues only with a minor delay the time needed to detect the failure and to change the tasks execution state Copyright 1996 Eonic Systems Virtuoso User Manual P1 47 Applications 6 5 Communication systems Another use of Virtuoso is to exploit the powerful routing capability without being concerned too much about the real time facilities The point is that Vir tuoso is a message based system Hence it is quite forward to construct a system where each node is running the Virtuoso protocol even if different processor types are in use and even if different types of transmission media are being used On each node one has to port the microkernel fairly easy because of the use of ANSI C while to accommodate the different transmis sion media one only has to implement a communication port driver The cur rent version of Virtuoso could in principle accommodate 64K nodes with each 64K tasks In practice generating this kind of system will involve addi tional work to change the system generation utility to work more efficiently and to write specific loaders
487. st always be ready to execute it is in fact the IDLE process of the nanok ernel All communication inside the nanokernel is performed using channels Sev eral types of channel exist The simplest type is used for synchronization only and corresponds to a counting semaphore Other types can be used to transfer data Given a good understanding of how the nanokernel operates a user could add his own channel types The Virtuoso microkernel managing the TASKs is build as an application on top of the nanokernel The main component is a PRHI process that exe cutes commands it receives from a channel When the channel is empty the microkernel process finds the next TASK to run replaces the nanokernel IDLE process by that TASK and performs the additional register swappings required for C tasks So when the nanokernel swaps in its IDLE process it Tl2 8 Virtuoso Binding Manual Copyright 1996 Eonic Systems Programming the nanokernel actually executes one of the microkernel TASKs The nanokernel is not aware of the manipulations performed by the micro kernel As far as it concerned there is only one PRLO process which it exe cutes whenever no PRHI process is ready to continue This makes it possible to use the nanokernel on its own 37 2 Internal data structures The user does not normally need to access the internal data structures used by the nanokernel The documentation in this section is provided only for a better u
488. status of the stack underflow empty full and overflow conditions DSP 96002 Programming Model Data ALU and Address Generation Unit M3 4 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Motorola 96K DSP DATA ALU 95 0 D9 H D9 M D9 L D9 D2 H D2 M D2 L D2 D1 H D1 M D1 L D1 D9 H DO M DO L DO 31 031 031 0 ADDRESS GENERATION UNIT M7 N7 R7 M6 N6 R6 M5 N5 R5 M4 N4 R4 M3 N3 R3 M2 N2 R2 M1 N1 R1 Mo NO RO 31 0 31 0 31 0 11 10 Exceptions permitted Exceptions masked 00 IPL 0 1 2 3 None 01 IPL 1 2 3 IPL O 10 IPL 2 3 IPL 0 1 11 IPL 3 IPL 0 1 2 FIGURE 19 Interrupt Mask bits 11 and 10 The SR format is shown hereunder Bit Nr Code Meaning Copyright 1996 Eonic Systems Virtuoso Binding Manual M3 5 Virtuoso on the Motorola 96K DSP 31 30 29 28 27 26 25 24 23 22 21 20 19 18 17 16 15 14 13 12 11 10 O NO AOON CO Bit 0 7 CCR Bit 16 23 IER SIOP SOVF SUNF SDZ SINX UN CC NAN S NAN OP ERR OVF UNF Bit 8 15 ER Bit 24 31 MR Loop Flag Reserved Interrupt Mask Interrupt Mask Flush to Zero Multiply Reserved Reserved Reserved Rounding Mode Rounding Mode IEEE Invalid Operation IEEE Overflow IEEE Underflow IEEE Divide by Zero IEEE Inexact Unordered Condition Not A Number Signaling NaN Operand Error Overflow Underflow Divide by Zero Inexact Accept Reject
489. stem can be traced back The main access point to this information is through the List monitor com mand of the debugger This was explained above The monitor is configured by two defines in the MAIN C files These can be modified if necessary the length of the circular buffer used to store monitoring information number of items stored the type of information to be traced This value can be any combination bit wise OR of the following values defined in iface h define MON_TSWAP 1 task swaps define MON_STATE 2 task state changes define MON_KSERV 4 kernel service calls define MON_EVENT 8 events define MON_ALL 15 all the above MONITMASK is used to initialize a global variable int monitmask that can be modified at run time e g if you want to monitor only part of an applica tion Each traced event adds a few micoseconds to the execution time The following information is listed the event number in the trace dt the time difference in high precision timer ticks with the previous event time the absolute time of the event object the kernel object related to the action action what happened described below P2 160 Virtuoso Reference Manual Copyright 1996 Eonic Systems Debugging environment under Virtuoso The object and action fields depend on the type of information For task swaps object is the task name and action will be
490. sters occupy the top 64 locations of the X data memory FFCO FFFF The off chip peripheral registers should be mapped into the top 64 locations to take advantage of the move peripheral data instruction MOVEP PORT A Port A is the memory expansion port that can be used for either memory expansion or for memory mapped I O An internal wait state generator can can be programmed to insert up to 15 wait states BCR register if access to slower memory or I O devices is required The Bus Wait signal allows an external device to control the number of wait states inserted in a bus access operation Bus arbitraion signals allow an external device to use the bus while internal operations continue using internal memory The expansion bus timing is controlled by the Bus Control Register BCR located at X F FFE This BCR consists of 4 subregisters Subregister Bits Controls Location of Memory External X Memory 12 15 External X Data Memory X 200 X FFCO External Y Memory 8 11 External Y Data Memory Y 200 Y FFCO External P Memory 4 7 External Program Memory P F00 P FFFF External I O Memory 0 3 External Peripherals Y FFCO F FFF PORT B General Purpose I O Port B can be viewed as 3 memory mapped registers that control 15 I O pins After a reset port B is configured as general purpose I O with all 15 pins as input by clearing all 3 registers M1 6 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Mo
491. stomer has placed an order and Eonic Systems has duly executed it This Agreement will remain in effect until Eonic Systems receives written notice of termination by Customer Eonic Systems may terminate this Agreement effective upon written notice thereof to Customer if Customer neglects to perform or observe any of the terms set forth in this Agreement This Agreement shall automatically termi nate upon any act of bankruptcy by or against Customer or upon dissolution of Customer 8 2 If any of the provisions or portions thereof of this Agreement are invalid under any applicable statute or rule of law they are to that extent deemed to be omitted 8 3 This Agreement shall be governed by the laws of the State of Belgium and the relevant laws of the European Community and Customer expressly LIC 4 Virtuoso User Manual Copyright 1996 Eonic Systems License agreement submits to jurisdiction therein by process served by mail on Eonic Systems at the address below 8 4 If Customer issues a purchase order memorandum or other written doc ument covering the Licensed Product provided by Eonic Systems it is spe cifically understood and agreed that such document is for Customer s internal purposes only and any and all terms and conditions contained therein shall be of no force or effect 8 4 This Agreement supersedes any and all prior representations condi tions warranties understandings proposals or agreements between Cus
492. store the initial value on return CFREE is the set of registers that are freely available to all functions the caller of a subroutine is responsible for preserving them if necessary The definition of these two sets largely determine what the micro Copyright 1996 Eonic Systems Virtuoso Binding Manual TI2 13 Programming the nanokernel kernel is expected to do when swapping tasks When a task is swapped out as a result of calling a kernel service which to the task is just a C function only the CSAVE set need be saved When a task is preempted which means that an interrupt handler has woken up the kernel the CFREE set must be saved as well Actually since most of the microkernel is written in C the CFREE set must be saved before the actual service requested by the interrupt handler is called Note ST is included in the CFREE set because it contains the flags tested by the conditional instructions bits 0 6 Other bits in ST have system con trol functions and should be treated as part of SYSSET In particular for cor rect operation of the nanokernel the SET COND flag bit 15 must remain reset at all times The SYSSET registers are used for system and peripheral control only They are never swapped and should be regarded as global resources Only very low level routines such as hardware drivers will ever need to access these registers The INTSET registers are those that must have been pushed on the stack when an
493. t 08000080 M2 4 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Motorola 68030 systems On the target processor board running the application with Virtuoso watchdog jumper disabled connected EPROM jumpers configured for 1 Mbit EPROM SCSI jumper connected cache jumper enabled not connected Boot ROM initialization parameters Processor Module Name CC112 Display NVDev contents on Reset Poweron y Boot from floppy disk SCSI port n Boot from hard disk SCSI port n Boot from EPROM n Boot from VMEnet port n Host SCSI ID 7 Hard disk controller SCSI ID 0 Floppy disk controller SCSI ID 1 Reset SCSlbus on Reset PowerOn n Reset VMEbus on Reset PowerOn n DPR Supervisory Access y DPR Non privileged Access y DPR Extended Access y DPR Standard Access y VMEbus DPR Base Address 08400000 Bus Request Level 2 Bus Request Release Mode Request Direct Release On Request Interrupt Handler VMEbus mask All levels disabled Interrupt Handler Local mask Level s 7 5 1 enabled VMEnet port 08000080 O ONO oO Sf NS N N N NYO NY YD NY HYD B NO oO FP WON s O DAN OO FP ON O 28 4 Additional information about the modules starter2 a As already mentioned earlier this module must be the first one linked into an executable This is because it contains the initialization that is normally done by the start routine for a
494. t be called by microkernel tasks only ADI 2 22 Virtuoso Binding Manual Copyright 1996 Eonic Systems Alphabetical List of nanokernel entry points 22 4 KS DisablelSR BRIEF Remove an ISR from the interrupt vector table CLASS 20 SaaS Interrupt service management e SYNOPSYS void KS_DisablelSR int isrnum e DESCRIPTION Disables the specified interrupt in IMASK and clears the corresponding entry in the interrupt vector table e RETURN VALUE none EXAMPLE KS_DisableISR 15 Disable ISR for link buffer 3 DMA Channel 5 SEEALSO KS_EnablelSR e SPECIAL NOTES Interrupt numbers are defined by their bit position in IMASK Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 2 23 Alphabetical List of nanokernel entry points 22 5 e BRIEF scape Bac e GLASS ee eos ees SYNOPSYS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES KS EnablelSR Install an ISR and enable the corresponding interrupt Interrupt service management void KS_EnablelSR int isrnum void isr void This C function is used to install or replace an interrupt handler It takes two parameters an interrupt number and a pointer to an ISR The pointer is entered into the interrupt vector table none extern void _host_irqh void KS_EnableISR 8 _host_irgh KS_DisablelSR Interrupt numbers are defined by their bit position
495. t conse quences 1 If an ISR calls a channel service that has a signal action any process swap that results from this call must be delayed until all interrupt han dlers have terminated These implies that only the PRHI_type of channel operations can be used as these do not invoke the swapper for a signal action there is no need to swap as the caller already has the highest priority When the last stacked interrupt terminates the swapper must be called to verify if a swap from the PRLO process to a PRHI process is necessary 2 An ISR must never call any channel service that has a wait action Doing so would also block all other interrupt handlers that are stacked below it as well as the current process Another way of seeing this is that an ISR cannot wait for something because it doesn t have a sep arate identity the producer of the external event another ISR has no means of representing who is waiting for it Note The 21060 is provided with a system stack When an external or a timer interrupt occurs MODE1 and ASTAT are pushed on that system stack The pop operation is performed by the RTI In our version of the kernel MODE1 and ASTAT are always pushed on the stack of the interrupted pro cess ADI 2 14 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the ADSP 2106x SHARC 21 7 10 The ISR level The 21060 has only one ISR level When entering the interrupt handler glo bal interrupts are enab
496. t handlers can communicate with processes using the same channel operations that are available to pro cesses There are however some restrictions In contrast to a process an interrupt service routine does not have a private workspace it executes on the stack of whatever process was interrupted Even if a processor supports a separate interrupt mode stack the C40 doesn t this will be shared by all interrupt handlers An ISR of course can itself be interrupted by another one so any number of interrupt handlers can be piled on top of each other on the same stack owned by the current pro cess This has some important consequences 1 If an ISR calls a channel service that has a SIGNAL action any process swap that results from this call must be delayed until all interrupt handlers have terminated These implies that only the PRHI_ type of channel opera tions can be used as these do not invoke the swapper for a SIGNAL action there is no need to swap as the caller already has highest priority When the last stacked interrupt terminates the swapper must be called to verify if a swap from the PRLO process to a PRHI process is necessary 2 An ISR must never call any channel service that has a WAIT action Doing so would also block all other interrupt handlers that are stacked below it as Copyright 1996 Eonic Systems Virtuoso Binding Manual Tl2 15 Programming the nanokernel well as the current process Another way of seeing
497. t indicates the location of the top of the SS and the status of the stack empty full underflow and overflow conditions m the PC Program Counter is a special 16 bit program control register is always referenced implicitly as a short word operand It contains the address of the next location to be fetched from program memory space m the 16 bit SR Status Register has the MR System Mode Register occupying the high order 8 bits and the CCR Condition Code Regis ter occupying the lower 8 bits The SR may be accessed as a word operand The MR and CCR may be accessed individually as word operands The MR is a special purpose register defining the current system state of the processor Special attention is given to the Interrupt Mask Bits These reflect the current priority level of the processor and indicate the IPL Interrupt Priority Level needed for an interrupt source to interrupt the processor These bits can be modified under software control The CCR is a special purpose register that defines the current user state of the processor Contents of the Status Register Bit Nr O MN WP HTD N CO Code LF T S1 S2 O lt N Z CME Meaning Loop Flag Reserved Trace Mode Reserved Scaling Mode Scaling Mode Interrupt Mask Interrupt Mask Reserved Limit Extension Unnormalized Negative Zero Overflow Carry Register MR MR MR MR MR MR MR MR CCR CCR CCR CCR CCR CCR CCR CCR M1 4
498. t the process with the highest priority when in a runable state is always scheduled first and will be executing until it no longer can 33 6 The Virtuoso implementation In practice Virtuoso is programmed as a set of high priority processes Note that the kernel is the only process allowed to run at the transputer high prior Copyright 1996 Eonic Systems Virtuoso Binding Manual T8 5 Virtuoso on the INMOS T2xx T4xx T8xx 33 7 ity and it is the only process allowed to talk directly to the external hardware such as the links and the event pin This means that all drivers and compo nent processes of the microkernel are in fact Virtuoso nanokernel pro cesses The difference with the implementation on other classical processors is that the nanokernel is implemented by hardware and that only the channel primitives are available for communication and synchronization The application tasks run at transputer low priority with a user defined lower priority The Virtuoso kernel will start up the tasks in order as defined by the user Afterwards the normal preemptive scheduling algorithm takes over Within each task the user can still use the normal FIFO scheduling mecha nism as long as his actions are restricted to the boundaries of the task So multiple subtasks can be run at the same priority with hardware support from the transputer When an application task needs to access the external hardware the kernel will execute
499. t the waiting time is limited to the specified number of ticks This function operates as a logical OR The occur rence of an event associated with any one of the semaphores in the list or a timeout will cause resumption of the waiting task Semaphore identifier of the event that occurred or the predefined constant ENDLIST if timed out K_SEMA Event K_SEMA istl TIMERA ENDLIST Event KS_TestMWT Listl 100 if Event ENDLIST printf Timed out after 100 ticks n else printf one of the three events happened n KS _ Test KS _ TestMW KS _ TestMWT KS Signal KS_SignalM P2 108 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services e SPECIAL NOTES In the situation where multiple events occur only the first one will be returned The rest will be serviced correctly on subsequent KS_ Test calls Note that a significant overhead can result when the semaphores reside on remote processors In Virtuoso Micro this service is implemented as a macro Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 109 Alphabetical List of Virtuoso microkernel services 11 71 e SUMMARY e CLASS e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES KS TestW Test a semaphore Semaphore int KS_TestW K_SEMA sema
500. ta arriving on the communication ports These events can even be simultaneous In the latter case the interrupts will result in a command packet being put on the microkernel command queue The microkernel handles all the commands one by one until the command queue is empty It eventually swaps the context and returns the CPU to the highest priority task that is runable 4 14 Virtual Single Processor operation Virtuoso provides the user with the same API Application Programmers Interface whether used on a single or on a multiple processor system For the user the differences are minor as the implementation of Virtuoso has made it possible to provide a virtual single processor The main thing to remember is that once a single processor Virtuoso pro gram has been properly developed the programmer will be able to keep his source program mostly intact when processors are added or when tasks or other microkernel objects are reallocated to remotely placed processors Some reasons for using Virtuoso can be 1 The need for more processing power or 2 The need to place some processing power physically close to a monitored or controlled unit Thanks to communication links like those on the transputer or on the TMS320C40 this is done relatively easy With Virtuoso one can improve the real time characteristics while keeping the original single processor source code intact Scalable processing power with scalable real time software that
501. tandard debugger command prompt is reissued 15 2 23 Exit TLDEBUG Invocation of this command causes the debugger to unblock all other tasks and to suspend operations Control is given to the highest priority task that is runnable 15 2 24 Help This command causes the debugger Command Menu to be displayed Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 167 Debugging environment under Virtuoso 15 3 The Workload Monitor Two kernel services have been added for reading the workload on a proces sor int KS_Workload void This returns the average workload as an integer value from 0 to 1000 and is to be read as tens of percentage void KS_SetWlper int T This sets the workload measuring interval to T ms T will automatically be reduced to the nearest limit of the range 10 1000 ms if a value outside this range is given The default value is 100 ms Note For calibration reasons the current implementation is based on the pres ence of a high resolution timer The workload measurement is not imple mented on target processors that only have a low resolution timer The workload monitor works as follows At any moment a processor executing a Virtuoso application can be occu pied in one of three different ways It can 1 execute kernel code 2 execute a microkernel task 3 or be idle While it is idle the processor actually executes the lowest priority microker nel task in t
502. target network is changed This paradigm is called the Virtual Single Processor as it allows a multi proces sor target to be programmed exactly as if it were a single processor In the same context Virtuoso also provides multiple levels of support allow ing a trade off to made of ease of programming for performance Two levels Copyright 1996 Eonic Systems Virtuoso User Manual INT 7 The history of Virtuoso are dedicated to handling interrupts one level consists of light context tasks called the nanokernel processes and the highest level is the preemptive priority driven C task level This level has a rich set of semantics is indepen dent of the network topology and hence is fully scalable Despite providing these rich features Virtuoso is still one of the smallest and fastest real time operating systems available The latest addition to the family is Virtuoso Synchro an application genera tor for synchronous dataflow applications It supports the specification simu lation emulation and implementation of mono and multi rate DSP applications on multi processor targets using a graphical user interface The generated code runs with minimum of input to output delays and memory requirements and can be used where even the smallest overhead from the kernel would be unacceptable Virtuoso is complemented by a range of support tools and libraries that make Virtuoso a complete programming environment designed to meet the needs
503. task 26 enqueue 4 bytes to a waiting higher priority task 26 SEMAPHORE OPERATIONS signal semaphore 7 signal to waiting high pri task 25 signal to waiting high pri task with timeout 33 signal to waitm 2 58 signal to waitm 2 with timeout 65 signal to waitm 3 72 ADI 2 40 Virtuoso Binding Manual Copyright 1996 Eonic Systems Task Level Timings signal to waitm 3 with timeout 78 signal to waitm 4 85 signal to waitm 4 with timeout 92 RESOURCE OPERATIONS average lock and unlock resource 6 MEMORY MAP OPERATIONS average alloc and dealloc memory page 6 Note involves no context switch S involves two context switches Timing is round trip time Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 2 41 Application development hints 25 Application development hints The easiest way to start is to copy and modify one of the supplied examples Some of the necessary files have fixed names so each application should be put in a separate directory The following files will be needed for each application SYSDEF The VIRTUOSO system definition file The SYSGEN utility will read this file and generate NODE1 C and NODE1 H MAIN1 C This contains some more configuration options and the C main function Copy from one of the examples A number of configuration options are defined in this file so they can be changed without requiring recompilatio
504. terrupt From the command prompt the user may enter any of the primary debugger commands which appear in the following paragraph All commands must be terminated by an Enter key The question mark displays the list of avail able commands wo In each command the user can scroll up and down using the and keys 15 2 2 Invoking the debugger from within your program The task level debugger task can be started by enqueueing the local Nodeld in the DEBUGIN queue The advantage of this method is the debugger is started almost immediately Example K_Node k k KS_Nodeld KS_Enqueue DEBUGIN amp k 4 Note Wirh older versions of Virtuoso semaphores were used to start up the task level debugger Refer the previous version of the manual if you still have an older version 15 2 3 Differences at system generation time In order to use the debugger you must create a task normally called TLDE BUG on the root processor and give it the highest priority in the system The entry point for the debugger task is a Virtuoso library function named tlde bug Next there is a POLLESC task that scans the keyboard fro the ESCAPE key You also need to define a queue normally called DEBUGIN for the debugger as well Finally your application must be linked with a version of the Virtuoso library that includes the debug code The example programs provided with the distribution show how this can be organ
505. tetee haatans e p E a ien P2 82 Ko SO SIAITMIMGN 3 devant chu date dos sta vita Ria E O a nie es P2 83 Ko JS SUIMG e E E E P2 84 KS Res meG sonk tes a a novel ea aee a Rea aAA OAE EE aee Ea Eaa P2 85 Soe VE E E E EE E A E E P2 86 KS 2S OMOW zai cs res eek cance a saves a a a od AER P2 88 IS CIV I eters fs acters te A A E EEA sere snanSe P2 89 KS SetE a ga ce ee ne er ee ere eer ten eee eee P2 91 KISS CIR MO ca sac sree tee aR PT Sl e ie NN OA is ac AT P2 92 PRS PS SIIC skids sattettarccataea E nd gs tate tenga ance cd Seance senate P2 93 REMELNI 9 eater eters nent eee ear E Pe Bee Sa Pee acre Cr rane ner eee P2 94 PRS SINAN ce iaee seca ea a a Oa ee Pare ace E O t P2 95 KS Sign lM erys sre aakit aA EAE A EASE IREE P2 96 KS Sleep rina oa e a E AEEA e aa aaa A E P2 97 KS 2S lather Sete a a a iia Motel em a tee tues cues ema seees P2 98 KS Slat E E estes ciih bed ae elelvecsh etl heelch E eet os eae P2 99 KS Start Timet ere a eaaa Ea aeea AEEA N anA aE P2 100 KS StOp Timer aeei nre E E a aE A E a E TAERE P2 101 KS Suspend mesis kantaten e e ve e A bu len each RE P2 102 KS USP OM Oats estar E A S mean neactcet mame mace wats P2 103 co aM E3114 0 anree an er eect er AUvaT eee eres te toe eee P2 104 KSESRASKPIIO ee ie eis Ades Saree tei Bee ee ONES Beet ta dees cada e P2 105 KS TOS tes ssn devatencenet Nostale a a N i e aa A tease P2 106 ao BRN B VN AE EE near erat Nae Ren Tener ett E N P2 107 Hes METSAN A
506. the delayed branch Instructions 1 and 2 are executed before the jump example 2 non signalling ISR using R2 R4 include lt def21020 h gt define HOSTSIG 8 defines event number for host segment pm seg_pmco global _irg_service makes it C callable endseg segment pm seg_pmco irq_service ADI 16 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Analog Devices 21020 DSP dm i7 m7 ASTAT dm i7 m7 MODE1 dm iv m7 r2 dm i7 m7 r4 lt body of ISR gt r4 dm 1 i7 r2 dm 2 i7 MODE1 dm 3 i7 ASTAT dm 4 i7 modify i7 4 RTI lt l Note also that for this release of Virtuoso Micro for the ADSP 21020 it is needed to disable interrupts before signalling the kernel When interrupts are enabled it is possible that an interrupt of higher priority interrupts one of lower priority Entering the kernel is a critical section and may not be inter rupted Therefore at that moment interrupts must be disabled Because it is advised to disable interrupts in a period as short as possible it must be done just before the jump The kernel will re enable interrupts as soon as the criti cal section is executed B VIRTUOSO CLASSICO There are two differences between writing IRQ s for VIRTUOSO MICRO and for VIRTUOSO CLASSICO 1 different set of registers that must be saved 2 the way the kernel is entered an example host inte
507. the device These are the routines that are called via the hardware interrupt vector table when an enabled interrupt is raised There are discussed in the previous chapter As an example we will describe a simple device driver used to transmit data TI1 10 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Texas Instruments TMS320C30 amp C31 packets over the C30 serial link Each packet is an array of 32 bit words The lower eight bits of the first word indicate the packet length We assume that the hardware has already been initialized 1 Task level interface void sendpacket int P KS_LockW SERIAL1 protect the device from other users seriall_send P start the transmission KS_EventW 6 deschedule until packet transmitted KS_ Unlock SERIAL1 release device to other users 2 Device control function This could have been written in C as well but putting it in the same ASM file as the ISR really simplifies the interface and minimizes the number of global variables SPIBASE set 000808050h hardwarebase address GLBCTL set 0 register offsets TXPCTL set RXPCTL set TIMCTL set TIMCNT set TIMPER set TXDATA set RXDATA set TXLINT set RXLINT set data portlbase word SP1IBASE hardware base address kernel signal codes IE bitnumber TOF WDAAHD oO fF W N
508. the exit sequence e EXIT CONDITIONS EXAMPLE listed below would correctly terminate the ISR pop ar2 pop arl pop aro popf r11 pop rll pop st reti This call terminates the ISR and does not return This ISR accepts the IIOFO external interrupt and sends EVENT 32 to the microkernel include traps inc ref _K_ArgsP def _ iiof0_isr etext __iiofO_isr push st push rll pushf rll push ar0 push arl Copyright 1996 Eonic Systems Virtuoso Binding Manual Tl2 25 Alphabetical List of nanokernel entry points push ar2 acknowledge interrupt if necessary lat PRHI_PSH ldi _K_ArgsP arl taR 32y ae2 nop lat ENDISRO E nop nop nop e SEE ALSO ENDISR1 SETISR1 pointer to microkernel input channel event number terminate the ISR TI2 26 Virtuoso Binding Manual Copyright 1996 Eonic Systems Alphabetical List of nanokernel entry points 38 4 SYNOPSYS ENDISR1 Terminates a level 1 ISR and conditionally invokes the process swapper Interrupt service management LATcond ENDISR1 ENDISR1 is defined in TRAPS INC DESCRIPTIONThis entry point must be called to terminate an ISR running at level 1 global interrupts enabled It decrements the level 1 interrupt counter and preforms a nanokernel process swap IFF a the calling ISR interrupted the PRLO process m a high priority process is ready to execute e ENTRY CONDITIONS The ISR should hav
509. the heap In the latter case the pointer to the KTImer object can be freely passed around but it becomes also the responsibility of the programmer to delete the KTimer object when it is not used anymore The mapping between member functions and kernel services is thus the fol lowing constructor calls KS_AllocTimer destructor calls KS_DeallocTimer KTIMER timer Start calls KS_StartTimer KTIMER timer Restart calls KS_RestartTimer KTIMER timer Stop calls KS_Stoptimer KTIMER A sample C application The D1P sample test program included in the distribution of Virtuoso Clas sico calls most of the kernel services A C version of this program called D1Pobj is also included We will highlight the differences between the two P2 188 Virtuoso Reference Manual Copyright 1996 Eonic Systems Microkernel C interface versions here We will first focus on the files generated by sysgen in the two cases and then we will discuss the changes in the program files 17 13 1 Sysgen generated files the sysdef file for the D1p and the D1Pobj sample programs are the identical Therefore the C and H files generated by sysgen are identical For D1Pobj we specify the ochCH flags to sysgen to let it also generate CPP and HPP files The following lines in the makefile reflect this the parts changed from D1P are underlined allnodes h sysdef pp v sysdef DD sysgen
510. the linked list and a pointer to it is returned If the channel is empty the calling process is swapped out and set to wait for the channel It will be rescheduled by the next call to the PRHI_ PUT service on the same channel e ENTRY CONDITIONS i4 pointer to linked list channel struct i3 pointer to PCS of calling process e EXIT CONDITIONS i1 pointer to list element rO r1 r2 r8 ASTAT i4 are corrupted EXAMPLE include macro h i4 dm CHANNEL PRHI_GETW SEEALSO PRHI_GET PRHI_PUT e SPECIAL NOTES This service must not be called from the low priority context or by an ISR ADI 2 26 Virtuoso Binding Manual Copyright 1996 Eonic Systems Alphabetical List of nanokernel entry points 22 8 PRHI_ POP BRIEF Remove next element from a stack channel e CLASS Process communication e SYNOPSIS PRHI_POP PRHI_ POP is defined in macro h e DESCRIPTION If the stack is not empty the top element is removed and returned to the caller The Z flag is reset If the stack is empty the Z flag is set and an unde fined value is returned The calling process is never swapped out as a result of calling this service e ENTRY CONDITIONS i4 pointer to stack channel struct e EXIT CONDITIONS r8 rO r1 r2 i4 ASTAT are corrupted If the stack is not empty r2 the element removed from the stack the Z flag is cleared If the stack is empty r2 undefined the Z flag i
511. the prompt is a decimal task number or the task s symbolic identifier as defined during the system generation procedure The entry is terminated by an Enter key 15 2 18 Suspend Execution of this command causes the specified task to be suspended The task cannot be restarted until it is resumed by another task or by operator P2 166 Virtuoso Reference Manual Copyright 1996 Eonic Systems Debugging environment under Virtuoso command via the debugger 15 2 19 Resume This command removes the state of suspension on the specified task If no other blocking condition exists the task is made ready to run 15 2 20 Abort This command causes the specified task to be aborted The waiting lists are cleared and the task abort handler will become executable upon leaving the debugger This command is not implemented for all target processors 15 2 21 Start A task may be restarted by the selection of this command The specified task is started at the entry point specified during the system generation proce dure This command is not implemented for all target processors NOTE The Abort and Start commands should be used with caution As the normal flow of execution is suspended when in the debugger Therefore after abort ing a task the user should exit from the debugger to allow the task to termi nate normally before restarting the task 15 2 22 Exit TLDEBUG This command causes the Task Manager Mode to terminate The s
512. the requested block size There are re organization and garbage collection techniques abounding but they fail one major test of a real time system The failure is in the time required to repair the fragmentation The amount of housekeeping time can not be controlled or even predicted Consequently the real time processing of an event needing the memory is indeterminate if normal memory alloca tion techniques are used Virtuoso implements a form of dynamic memory management that partitions the memory in static blocks At system definition time the available RAM memory is divided into one or more memory maps where each map is logi cally made up of a number of fixed size blocks The size of the blocks and number of blocks per map is user defined When a task requires memory for local storage by the KS_Alloc microkernel service Virtuoso will allocate memory a single block from the specific partition memory pool A pointer to the base address of the block is returned to the requesting task If no mem ory is available in the specified partition a NULL value 0 is returned When the memory is no longer needed by a task the block can be released back to the memory pool via the KS_Dealloc microkernel service The partitioned memory technique however does not in itself prevent the loss of an event due to unavailable memory It is the responsibility of the sys tem designer to configure the system to have enough allocatable memory in the approp
513. the string Swapped in The task name idle refers to the NULL task For task state changes object is the task name and action will be the name of the bit that was changed prefixed by bit set or bit reset A task is ready to run if all its state bits are reset The state bits are described in sec tion 14 2 5 above For events the object field is not used and the action field shows the event number The MON_KSERV option shows all commands received by the kernel on the current processor Some of these correspond to kernel services requested by local tasks In this case the object field shows the task name Others are commands that arrive from other processors in the network In this case the node ID of the source of the command will be shown The commands shown in the action field are NOP KS_Nop USER KS_User READWL KS_Workload SIGNALS KS_ Signal SIGNALM KS_SignalM RESETS KS_ResetSema RESETM KS_ResetM WAITS_REQ KS_Wait T WAITS_RPL internal message for KS_Wait T WAITS_TMO id WAITMANY KS_WaitM T WAITM_REQ internal message for KS_WaitM T WAITM_RDY id WAITM_CAN id WAITM_ACC id WAITM_END id WAITM_TMO id INQSEMA KS_InqSema LOCK_REQ KS_Lock W T LOCK_RPL internal message for KS_Lock W T LOCK_TMO id Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 161 Debugging environment under Virtuoso UNLOCK ENQUE_REQ ENQUE_RPL ENQUE_TMO DEQUE_REQ DEQU
514. they must never wait on the channel i e always use PRHI_GET If the list is empty correct behavior is to call YIELD and try again later In the Virtuoso network the Srce field of a command packet identifies the sending node and it is used as a return path for reply messages The same field also has a secondary function since all packets sent or received through the network are allocated from the K_ArgsFree list they should be deallocated after use The network transmitters always free a packet after it has been sent The microkernel deallocates a packet if the Scre field is not zero Consequently command packets not allocated from the free list must have their Scre field set to zero to prevent deallocation Note we are aware of the fact that this logic is a bit confusing Future ver sions of the microkernel will probably use a separate flag to indicate if a packet was dynamically allocated Interrupt handlers and PRHI processes can request a microkernel service by building a command packet and pushing a pointer to it on the microkernel input channel The only services that can be safely called are the equivalents of KS_Signal and KS_SignalM Also note that using events will be faster than signals The code fragments below show how to perform a KS_Signal or KS_SignalM call from within the ISR In this example the command packet is created and initialized in C but the same thing could be done entirely in assembly language The fun
515. this as a service using a small driver process Memory mapped peripherals can be accessed directly by the application tasks Some of the communication links are not available to the application tasks For example links that are purely used for building the network The routing layer of the Virtuoso kernel uses these links to transfer data as well as remote service calls from one processor to another Requirements for embedded real time systems Various real time kernels are on the market that provide preemptive schedul ing services In addition the application tasks need to be able to communi cate in a synchronous and asynchronous way They need to be able to synchronize and the kernel needs to be able to allocate memory protect common resources and provide timer related services In an era where pro cessing technology is changing at a very rapid pace a portable kernel writ ten in a high level language is essential The result was RTXC MP the first true real time kernel for the transputer The second generation of this devel opment was called virtuoso because it is more than a real time kernel itis a programming system It is the basis of a series of real time dedicated prod ucts Embedded real time systems have a number of characteristics that enable the designer to relax some of the conditions to be met 1 Often the application will be static 2 Input and controlling actions are known in great detail including their dura
516. this is that an ISR cannot wait for something because it doesn t have a separate identity the producer of the external event another ISR has no means of representing who is waiting for it The C40 does not support a separate interrupt mode an ISR cannot deter mine whether it interrupted a foreground process or another ISR by examin ing the processor state only The Virtuoso nanokernel defines a software protocol that must be observed by all interrupt handlers to implement the logic described above In this system an interrupt handler can run at either of two execution levels The ISRO level All interrupt handlers are entered at this level Interrupts are disabled globally GIE 0 and the ISR is not allowed to re enable them Consequently at any time there can be only one ISR running at this level It runs entirely in the background and remains unknown to the kernel until it terminates by calling the ENDISRO service At that point the nanokernel will verify if a process swap is required and allowed The condition tested is the logical AND of a NANOK_PRHI 0 the current process is PRLO NANOK_HEAD 0 a PRHI process is ready to execute NANOK_CRIT 0 no other ISR stacked below this one If the interrupt handler did not call a channel operation with a SIGNAL action the condition above can never be satisfied so in this case the ISR is allowed to terminate by a normal ISR exit sequence popping all saved registers
517. this mailbox object 2 If the last three or more characters of the ID name are identical to the P2 178 Virtuoso Reference Manual Copyright 1996 Eonic Systems Microkernel C interface first characters of the object class name then these identical charac ters will be replaced by the class name The remainder of the ID name will be converted to lowercase except for the first character which is forced to uppercase Examples HIPRIOTASK becomes HiprioTask HOSTRES becomes HostResource 3 In case we don t find part of the object type name in the Id given by the user we convert the ID name to lowercase except the first which is converted to uppercase and append the object type name Example a task object named MASTER becomes MasterTask For acomplete example listing we refer to section 17 13 on page 188 17 3 KTask The class that encapsulates kernel tasks has the name KTask The class definition is as follows class KTask private K_TASK m_TaskID construction destruction public KTask K_TASK taskid access functions public K_TASK GetID operations public void void void void void void const SetEntryFunction void taskentryfunction void SetPrio int priority Start Abort Suspend Resume The constructor takes the task ID number as an argument The GetID member function allows retrieving the ID of a task object
518. ti 4 for i 0 i lt 1000 i KS_WaitMT slist 5000 slist 3 SEM4 for i 0 i lt 1000 i KS_Wait slist for i 0 i lt 1000 i KS_WaitMT slist 5000 void master void int k puts Type to start a benchmark sequence puts Demo can be terminated with C n while 1 k server_pollkey if k server_putchar k if k benchm 17 14 Traps and Pitfalls of C Caution is required when a developer wishes to use global or static variables that are instances of C classes Initialisation of C objects that are not allocated on the stack is done before the main routine is executed The C compiler will generate initialisation code for all global or static C objects This code will initilaise these C objects by calling their constructor with the parameters supplied by the user C object initialisation code will thus run before the main routine is exe cuted and thus also before the kernel is initialised One may thus not use any kernel service calls in the constructors of objects that have global or static scope If any C object initialisation requires calling kernel services Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 197 Microkernel C interface then a separate initialisation member function must be added to the class The programmer must then call this initialisation function on his objects after the kernel_init cal
519. ting demands No algorithm exists to find the optimum solution For the moment use your common sense and the debugging monitor to fine tune the system Customized versions and projects Virtuoso is delivered as a standard kernel with standard features and pro vides an adequate solution in most circumstances This is especially true for embedded systems where maximum performance is desired while memory usage is minimized and the system is rather static over its life time In some cases more functionality is wished such as 1 capability to monitor the system at runtime 2 capability to dynamically change the system 3 capability to use a different scheduling algorithm Eonic Systems is aware of these special requirements especially as most of these less standard features are typical for distributed and parallel process ing systems As such Eonic Systems is already working on new Virtuoso versions that support dynamic real time features and fault tolerance Cus tomers with special needs can be supported in different ways 1 by adapting the kernel themselves 2 by buying a customized version 3 talking to our team to find an alternative but equivalent solution As the kernel itself is highly modular although compact most customer spe cific functions can be provided on short notice If you would prefer Eonic Systems to integrate the kernel as part of a full cus tom solution this can be negotiated For more information contact Eon
520. tion e SYNOPSIS PRHI_WAIT PRHI_WAIT is defined in macro h e DESCRIPTION If the event counter is not zero it is decremented an control returns to the caller If the event counter is zero the calling process is swapped out and set to wait for the channel It will be rescheduled by the next call to the PRHI_SIG service on the same channel e ENTRY CONDITIONS i4 pointer to signal channel struct i3 pointer to PCS of calling process e EXIT CONDITIONS rO r1 r2 are corrupted EXAMPLE include macro h wait for event on SYNC_CHAN i4 dm SYNC_CHAN PRHI_WAIT the event has happened SEEALSO PRHI_SIG e SPECIAL NOTES This service must not be called from the low priority context or by an ISR ADI 2 32 Virtuoso Binding Manual Copyright 1996 Eonic Systems Alphabetical List of nanokernel entry points 22 14 PRLO_PSH BRIEF This call is for internal use only and is not exactly the equivalent of PRHI_PSH for the PRLO process This call assumes that a PRHI process is waiting for the channel and will crash the system if there isn t PRLO_PUSH is used by the K_taskcall function to send command packets from a task to the microkernel process Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 2 33 Alphabetical List of nanokernel entry points 22 15 YIELD e BRIEF Yield CPU to next nanokernel process CLASS Process management e SYNOPSIS
521. tized tasks Well suited when preemp tive scheduling is needed and the appication has moderate interrupt requirements Virtuoso Classico a tight integration of Virtuoso s nanokernel and Virtu oso s microkernel The microkernel provides fully distributed high level semantics with no source code changes when kerrnel objects or user tasks or moved in a processor network or when the system topology is changed Copyright 1996 Eonic Systems Virtuoso User Manual INT 1 Introduction Virtuoso Modulo 0 to VI contain a complete range of libraries in optimized assembly covering vector and matrix functions filters FFT EISPACK eigen value functions BLAS Basic Linear Algebra Subroutines and 2 dimen sional image processing All written in optimized assembly Part of the librar ies were developed by Sinectoanalysis from Boston MA and adapted for Virtuoso The package is complemented by a board specific host server that boots the target network and provides standard I O PC graphics and heap allocation functions For the rest of the manual we will often use the term Virtuoso as the context makes it clear what product offering is being discussed Virtuoso currently supports the following processors ARM INMOS T2xx T4xx T8xx T9000 TEXAS INSTRUMENTS TMS320C30 C31 C40 Motorola 68xxx 68HC11 68HC16 Intel 80x86 real mode MIPS R3000 Motorola 96K 56K Analog Devices 21020 2106x Pine amp OakDSPCore contact Eonic Systems
522. tntrnsrrrns terrne M3 25 Task Level TiMINJS sirrdir isenana uae aea ha aaiae ka RAAST Ap Skeutedeapenteues M3 26 Application development hints esseeseeessseesesesssrresrrrtteri retretter tetrnnnesnnnnstnnn tennene M3 27 Virtuoso on the Motorola 68HC11 M4 1 Virtuoso on the Motorola 68HC16 microcontroller M5 1 Virtuoso on the Mips R3000 systems R1 1 Virtuoso on the INMOS T2xx T4xx T8xx T8 1 IMTFOCUCTIONY zinte a a e waded e ecdeavt a a a E T8 1 The transputer an example component for distributed processing ceee T8 1 Process control with transputers nccicsesescteectcncs deapesiac sd vedaaccndsstenheda oi slddasduabees tavbeeeudes T8 2 A solution based on process priority Se sexscrrete nested ocelot el Meet ee ene T8 3 Modifying the FIFO scheduler on the transputer c ccccceeeeeeeeeeeeeeeeceeeeeeeeeeseeeees T8 4 The Virtuoso implementation a tins ecesiees shed sacueeasecdact epee cuenaddadessaneespesdereeeveutagansdenesterens T8 5 Requirements for embedded real time systems cceceeeeeeeeeeeeee eee eeeeeeenteeaeeeeneee T8 6 Small grain versus Coarse grain parallelism ccccceeececeeeeeeeeeeeeeneeeeeeseaeeeeeeenaeeeees T8 7 Additional benefits from Virtuoso on the transputer eecceeeeeeeeeeeeeeeeeeeeeeeeeeneeeees T8 8 Device drivers with Virtuoso on the INMOS transputer 0 cceeeeceeeeeeeeeeteeeeees T8 8 Performance results nih 126s eadsnccsahsadaeseteauroadess ove ntudarastnc dude
523. torola 56K DSP The 3 registers are Location Bits Use Port B Control Register PBC X FFEO 0 0 Parallel I O 1 Host Interface Port B Data Direction Register X FFE2 0 14 0 Input PBDDR 1 Output Port B Data Register X FFE4 0 14 Data Host Interface The Hl is a byte wide full duplex double buffered parallel port which may be directly connected to the data bus of a host processor It is asynchronous and consists of 2 banks of registers one bank accessible to the host processor and a second bank accessible to the DSP CPU The DSP CPU views the HI as a memory mapped peripheral occupying 3 24 bit words in data memory space It may be used as a normal memory mapped peripheral using polling or interrupt techniques The memory map ping allows the DSP CPU to communicate with the HI registers using stan dard instructions and addressing modes The MOVEP instruction allows HI to memory and memory to HI transfers without using an intermediate regis ter The 3 registers are the following Location Bits Use A Host Control Register HCR X FFE8 DSP CPU HI flags Host Command Interrupt Host Transmit Interrupt Host Receive Interrupt DMA HOST HI flags Host Command Pending Host Status Register HSR X FFE9 A Host Transmit Data Empty O NWN OH DN W Host Receive Data Full Host Receive Data Register X FFEB Host Transmit Data Register X FFEB Copyright 1996 Eonic Systems Virtuoso Binding Manual M1
524. tuation where multiple events occur only the first one will be returned The rest will be serviced correctly on subsequent KS_Wait M calls Note that a significant overhead can result when the semaphores reside on remote processors This call is only available on Virtuso Micro Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 115 Alphabetical List of Virtuoso microkernel services 11 77 KS WaitMT e SUMMARY Wait on multiple semaphores with time out CLASS Semaphore e SYNOPSIS K_SEMA KS_WaitMT K_SEMA list K_TICKS ticks e DESCRIPTION The KS WaitMT microkernel service performs the same function as the KS _WaitM microkernel service except that the waiting time is limited to the specified number of ticks This function operates as a logical OR The occur rence of an event associated with any one of the semaphores in the list or a timeout will cause resumption of the waiting task e RETURN VALUE ENDLIST if timed out e EXAMPLE Event istl TIMERA IST KS_WaitMT Listl ENDLIST Event if Event else SEEALSO KS_Wait KS_WaitM KS_ Signal KS_SignalM e SPECIAL NOTES Semaphore identifier of the event that occurred or the predefined constant 100 printf Timed out after 100 ticks n printf one of the three events happened n In the situation where multiple events occur
525. twork drivers other PRHI processes and interrupt han dlers A pointer to this channel is exported in the C variable K_ArgsP Two types of data can be pushed onto this channel 1 Small integers 0 63 are interpreted as events Events are simple binary signals that a task can wait for using the KS_EventW service Most events will be generated by interrupt handlers and driver processes For the 21020 version event numbers have been assigned as follows ADI 26 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Analog Devices 21020 DSP m 0 31 all interrupts provided by the 21020 a 48 timer event m rest are free 2 All other values pushed onto the microkernel input channel are interpreted as a pointer to a command packet Command packets are the primary form of communication used within the Virtuoso system They are used by the tasks to request microkernel services sent across the Virtuoso network to implement remote kernel calls and put on waiting lists to represent a task that is waiting for something It is outside the scope of this manual to present a complete description of the command packet data format The basic struc tures and the command codes are defined in K_STRUCT H The microkernel maintains a list of free command packets implemented as a list based channel A pointer to this channel is exported in the C variable K_ArgsFreeP Other PRHI processes can get command packets from this pool but
526. ueW KS Dequeue KS _DequeueW KS_DequeueWT e SPECIAL NOTES The size parameter is the number of 8 bit bytes to be queued It should be equal to the width of the queue which implies enqueueing only one entry at a time or unpredictable side effects may occur Care needs to be taken when specifying the size parameter on systems where characters are stored one per word or where sizeof does not return the number of 8 bit bytes in a type Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 47 Alphabetical List of Virtuoso microkernel services 11 19 e SUMMARY e CLASS e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE SEEALSO e SPECIAL NOTES KS EventW Wait for an event to be signalled Processor specific void KS_EventW int IRQ This call will put the calling task in an EVENT WAIT State When the event is raised or was raised before the service call the call will return and the event is cleared NONE while 1 KS_EventwW 7 Wait for an event of type 7 do something with the event ay KS EnablelSR KS_DisablelSR This service is processor specific and the prototype may vary according to processor type P2 48 Virtuoso Reference Manual Copyright 1996 Eonic Systems Alphabetical List of Virtuoso microkernel services 11 20 e SUMMARY e SYNOPSIS e DESCRIPTION e RETURN VALUE EXAMPLE S
527. ueW string set ANYTASK string send message to waiting high priority task and wait i 1 Message amp et Header only 40d n et 4096 i 1 i lt 1000 Demogqx1Queue EnqueueW string amp et nqueue 1 byte et i 1 nqueue 1 byte to a waiting higher priority P2 194 Virtuoso Reference Manual Copyright 1996 Eonic Systems Microkernel C interface testl cpp KS_Elapse amp et for i 0 i lt 1000 i Semaphorel Signal et KS_Elapse amp et et ticktime et 1000 convert to us printf FORMAT signal semaphore et KS_Sleep 250 Semaphorel1 Reset HisTask Start KS_Elapse amp et for i 0 i lt 1000 i Semaphorel Signal et KS_Elapse amp et et ticktime et 1000 convert to us printf FORMAT signal to waiting high pri task et KS_Sleep 250 KS_Elapse amp et for i 0 4 lt 1000 i Semaphore4 Signal et KS_Elapse amp et et ticktime et 1000 printf FORMAT signal to waitm 4 with timeout et KS_Sleep 250 Copyright 1996 Eonic Systems Virtuoso Reference Manual P2 195 Microkernel C interface test1 cpp KS_Elapse amp et for i 0 i lt 5000 i DemoResource Lockw DemoResource Unlock et KS_Elapse amp et et ti
528. upted process One of the saved registers contains an entry to be put into the kernel FIFO Since an interrupt may occur at any time there are two cases to consider A task was interrupted This means the ISR has been using the task s stack and has already partially saved its context In this case the rest of the task s context is saved and control is given to the kernel Note that the regis ters pushed onto the task s stack by the ISR have become part of the task s saved context This means that for all practical purposes the ISR has ended Allowing the ISR to continue when the task is rescheduled would be useless anyway The kernel itself was interrupted and the ISR has been using the kernel s stack In the case the kernel will jump to an ISR exit sequence to restore its registers and continue Again the ISR has ended For the TI C30 and C40 implementations of Virtuoso the following conditions should be satisfied when an ISR branches to kernel_sign_entry interrupts are disabled the return address and the saved ST and RO registers are still on the stack The following sequence would perform a normal interrupt return POPF RO POP RO POP ST RETI with RO event number As an example this is the ISR used to maintain the TICKS time The inter rupt is generated by a hardware timer The ISR updates a local variable hitime and then passes an event to the kernel In the final version a dela
529. ut sign Reserved bit test flag for system registers RO FLAGO value FLAG1 value FLAG2 value FLAGS value Reserved CACC bits 18 4 3 Sticky arithmetic status register STKY STKY is also a 32 bit register The bits can be set by ALU operations By reading this register the service routine for one of these interrupts can deter mine which condition caused the interrupt The routine also has to clear the STKY bit so that the interrupt is not still active after the service routine is done An overview of the bits is given below Bit N OA AON OO A Oo 10 16 17 18 19 20 21 22 Name AUS AVS AOS AIS MOS MVS MUS MIS CB7S CB15S PCFL PCEM Definition ALU floating point underflow ALU floating point overflow ALU fixed point overflow Reserved ALU floating point invalid operation multiplier fixed point overflow multiplier floating point overflow multiplier floating point underflow multiplier floating point invalid oper Reserved DAG1 circular buffer 7 overflow DAG2 circular buffer 15 overflow Reserved PC stack full PC stack empty Copyright 1996 Eonic Systems Virtuoso Binding Manual ADI 7 Virtuoso on the Analog Devices 21020 DSP 23 SSOV status stack overflow 24 SSEM status stack empty 25 LSOV loop stack overflow 26 LSEM loop stack empty 27 31 Reserved 18 4 4 Interrupt latch IRPTL and Interrupt Mask IMASK These two registers are used in combination with interrupts B
530. uter high priority queue c Channel I O to threads which are not generated from the same master task ChanAlloc ChanOutTimeFail ChanInTimeFail For external links use KS_LinkinW and KS_LinkoutW For reading the event pin use KS_EventW For intertask communication you can use message calls d Semaphore functions within threads which are not generated from the same master task For intertask synchronization you can use the Virtuoso semaphore functions Note the differences between the types SemAlloc e Memory allocation malloc calloc realloc free e All standard file I O routines like printf scanf etc They don t work as they require that the server program that comes with the compiler is used Use the supplied I O library functions Copyright 1996 Eonic Systems Virtuoso Binding Manual T8 13 Virtuoso on the INMOS T2xx T4xx T8xx 33 15 Specific routines of the Logical Systems compiler not to be used by the tasks a LSC Timer functions which can cause a descheduling operation ProcTimerAlt ProcTimerAltList ProcAfter ProcWait Equivalent Virtuoso functions are provided b Thread functions interfering with Virtuoso ProcReschedule ProcRunHigh ProcPriPar PForkHigh ProcAlloc ProcFree SetHiPridQ SetLoPriQ ProcToHigh ProcToLow Within each Virtuoso task it is however perfect
531. vel One of the processes is the microkernel itself that manages the preemptive scheduling of the tasks see below The following example tested on a 40 MHz C40 illustrates the resulting unprecedented performance Two processes successively signal and wait on each other using a intermediate counting semaphore Signal Task switch Wait Signal Task switch Wait Round trip time measured 5775 nano seconds or less than one microsecond per operation Processes have the unique benefit of combining the ease of use of a task with the speed of an ISR In a multi processor system they play an essential role Without the functionality of the processes the designer has the option or to program at the ISR level and hence often disabling interrupts because of critical sections or to program at the C task level but resulting in much increased interprocessor latencies This is due to the fact that in an multipro cessor system interprocessor communication has to be regarded as high priority interrupts because if not acted upon immediately it can delay the processor that is the source of the interrupt LEVEL 4 The microkernel level tasks This is the standard C level with over 70 microkernel services This level is fully preemptive and priority driven and each task has a complete processor context It provides a high level framework for building the application as explained in the previous paragraph Programming at this level provides for ful
532. ves So for example sprintf Buffer Hello World n can be written in the application without any problem rtxcmain c This module contains the main function main Here all initialization rou tines for the kernel structures are called In main the DUART is also ini tialized and programmed to give tick interrupts every 1 millisecond Finally all tasks of the EXE group will be started As main is part of the idle task of the kernel main will never be exit ed Instead an endless loop is called that performs some statistics tidebug c tlmonit c These modules are only needed when the task level debugger of Virtuoso is wanted tstdio c This module contains all standard Input Output services supported by Virtu oso If no standard I O is wanted this module must not be linked with the application 28 5 Server program for CompControl VME system board running on OS 9 This document file contains additional information concerning the structure Copyright 1996 Eonic Systems Virtuoso Binding Manual M2 9 Virtuoso on the Motorola 68030 systems 28 5 1 28 5 2 and internals of the server program for Virtuoso Purpose of the server program The server program resides on the first VME card in a VME node and has several tasks It is written to run on the host operating system OS 9 In this way one can view the server program as a bridge between Virtuoso running on the other pro
533. with interrupts enabled In this way the kernel pro vides automatic reentrancy for long winded ISR s This could be difficult to achieve otherwise In most cases the hardware related processing can be done using very few instructions and only a small subset of the processor registers Therefore this type of interrupt handler can be very short and latency will be minimal Separating the hardware and the system part makes is possible to opti mize each of them individually Inside the ISR full use can be made of any processor specific features When control moves to the task level the full power of the kernel is at the disposal of the user In order to understand how control is passed from an ISR to the kernel we should have a look at how the kernel operates in the first place The kernel maintains a FIFO buffer of things to do It reads and handles entries in this FIFO the one after the other When the FIFO becomes empty the kernel determines which task should run next and releases the CPU Each thing to do is represented by a single word When this word is a small integer typically 64 it is interpreted as an event number Some events i e from the TICKS timer or from the routing layer inan MP system are handled internally by the kernel The others can be waited for by a task using KS _EventW If the FIFO entry is not a small integer it is assumed to be a pointer to a command packet There are three
534. would introduce needless overhead of context saving The kernel when jumped to by label Fkernel_sign_entry will perform a context save for all non pre served registers In this case it is advised to make a task that waits for an event with kernel service KS_EventW n and that calls this C function after it is waked up by a signal to event number n Copyright 1996 Eonic Systems Virtuoso Binding Manual M1 17 Virtuoso on the Motorola 56K DSP 27 7 Alphabetical list of ISR related services Fkernel_sign_entry for entering the kernel from within an ISR single processor version only KS_Eventw for waiting for an interrupt at the task level KS _EnableISR for installing an ISR KS DisableISR for removing an ISR M1 18 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Motorola 56K DSP 27 7 1 e SYNOPSIS BRIEF gil Sk SS EXAMPLE SEEALSO e SPECIAL NOTES Fkernel_sign_entry Label jumped to when entering the kernel from within an ISR This service gives a signal to the kernel with an event code numbered between 0 and 63 inclusive A task can wait for the occurrence of such a sig nal by using kernel service KS_EventW n KS _EventW The kernel signalling service assumes that certain conventions are followed by the ISR 1 Stack Pointer R6 must be incremented at the very start of the I
535. xample is given for each class of ISR Example 1 a non signalling ISR uses registers NO N2 RO and R1 move R6 move NO y R6 4 move N2 y R6 4 move RO y R6 4 move R1 y R6 4 lt body of ISR gt move R6 move y R6 R1 move y R6 R0 move y R6 N2 move y R6 N0O PET prior increment of R6 save NO save N2 save RO save R1 post decrements are faster restore R1 restore RO restore N2 restore NO finito Example 2 a signalling ISR using R4 and M4 as extra registers move R6 prior increment of R6 move X 1 R6 save X move B10 1 R6 save B move B2 y R6 move R1 x R6 save R1 move R2 y R6 4 save R2 move R4 y R6 4 save R4 move M4 y R6 4 save M4 lt body of ISR gt move R6 post decrements are faster M1 16 Virtuoso Binding Manual Copyright 1996 Eonic Systems Virtuoso on the Motorola 56K DSP move y R6 M4 restore M4 move y R6 R4 restore R4 NO DECREMENT move SIGNUM B1 load B1 with event signal number jmp Fkernel_sign_entry signal the kernel If a C procedure is called from an ISR all registers that are not preserved across a procedure call see paragraph 27 5 3 for a list of preserved regis ters have to be saved However for a signalling ISR it is not advised to make a subroutine jump to a C function from within the ISR as this
536. xception Status SSI Transmit Data SSI Transmit Data with Exception Status SCI Receive Data SCI Receive Data with Exception Status SCI Transmit Data SCI Idle Line SCI Timer NMI Reserved for Hardware Development Host Receive Data Host Transmit Data Host Command Default Available for Host Command Available for Host Command Illegal Instruction The 32 interrupts are prioritized into 4 levels Level 3 the highest priority level is not maskable Levels 2 0 are maskable The priority level of an interrupt can be programmed to 0 1 2 or disabled Interrupts are processed in the following way a hardware interrupt is synchronized with the DSP clock and the interrupt pending flag for that particular interrupt is set An interrupt source can have only 1 interrupt pending at any given time m all pending interrupts are arbitrated to select the interrupt which will be processed The arbiter automatically ignores any interrupts with an IPL lower than the interrupt mask level in the SR and selects the remaining interrupt with the highest IPL a the interrupt controller freezes the PC and fetches 2 instructions at the 2 interrupt vector addresses associated with the selected interrupt m the interrupt controller puts the 2 instructions into the instruction stream and releases the PC The next interrupt arbitration is then begun Two types of interrupt may be used fast and long The fast routine consists of the 2 automatically ins
537. xecu tion This grainsize must be large enough so that the overhead of requesting microkernel services and the resulting context switches is acceptable A standard Virtuoso task is written in C and task swapping implies that a full context is being saved partly by the C compiler upon the function call and partly by the microkernel to save the rest of the registers Process Level enabled All registers saved by microkernel LL aah Predefined subset of registers saved by nanokernel As many as ISR1 needs saved by IRS1 As many as ISRO needs saved by IRSO FIGURE 11 The four processor contexts considered by the Virtuoso system P1 34 Virtuoso User Manual Copyright 1996 Eonic Systems Functional support from Virtuoso In practice especially on DSPs and high end RISC processors one also needs units of execution with a smaller context and hence less context switching time These can only be obtained by writing assembly code unfor tunately we don t control what context the compiler uses The Virtuoso kernel manages each part of the context as if it were part of the CPU resource allocated to a unit of execution As such only those parts that are required are saved and restored by the kernel In total Virtuoso distinguishes four levels 1 The ISRO level ISR with global interrupts disabled 2 The ISR1 level ISR with global interrupts enabled 3 The Virtuoso nan
538. yMap K_MAP memmapid access functions public operations public void Alloc void memblockaddress void AllocW void memblockaddress void AllocWT void memblockaddress K_TICKS timeout void Dealloc void memblockaddress int NumberOfFreeBlocks The constructor takes the memory map ID number as an argument Other member functions called upon a KMemoryMap object will result in kernel service calls with the memory map ID of the memory map object as the first parameter The mapping between member functions and kernel services is the following memmap Alloc calls KS_Alloc MMID memmap AllocW calls KS_AllocW MMID memmap AllocWT calls KS_AllocWT MMID memmap Dealloc calls KS_Dealloc MMID memmap NumberOfFreeBlocks calls KS_InqMap MMID KResource Objects representing kernel resource are of the class type KResource The class definition is as follows P2 186 Virtuoso Reference Manual Copyright 1996 Eonic Systems Microkernel C interface class KResource private K_RES m_ResourcelID construction destruction public KResource K_RES resourceid j access functions public K_RES GetID operations public void Lock void LockW void LockWT K_TICKS timeout void UnLock The constructor takes the resource ID number as an argument
539. yed branch should be used of course Copyright 1996 Eonic Systems Virtuoso Binding Manual TIl 9 Virtuoso on the Texas Instruments TMS320C30 amp C31 35 6 2 _timerl_irgh push ST Save minimal register set push RO pushf RO ldi timerldivd RO hitime timerldivd addi hitime RO sti RO hitime ldi TIMERI1SIG RO Signal the TIMERISIG event b kernel_sign_entry This is a very simple ISR it does a minimum of local processing and always hands over the interrupt the kernel A more complex example can be found at the end of the next section Parts of a device driver To implement a device driver in the Virtuoso environment in general three pieces of code will be needed 1 An application interface at the task level These are the procedures called directly by the application code In most cases these functions should 1 Protect the device by locking a resource 2 Issue a number of device commands 3 For each command deschedule the caller until the command has been exe cuted This is done by calling KS_EventW 4 Unlock the device for other users These routines are not needed if the device is used by the kernel only e g for internal routing 2 One or more low level device control procedures These are used to send commands and parameters to the low level interrupt handlers in a structured way 3 An interrupt handler for each interrupt used by

Download Pdf Manuals

Related Search

Related Contents

Consultee Access User Guide  スライド 1  User Manual - Cyagen Biosciences    USE & CARE GUIDE  Snapper L1226E User's Manual  AL0484 Home Oxygen Paediatric User Guide  

Copyright © All rights reserved. Failed to retrieve file