dsp_K frequently asked questions

16 Febraury, 2001

Copyright Notice
Copyright (C) Julian Rose, Sussex, U.K. The software and corresponding documents are distributed under license.

Overview | General | Kernel | Build Time | Run Time | License

0. Overview

This document is part of the "digital signal processor kernel" (dsp_K) software distribution and a licensed DSP_K DESCRIPTION document. It provides answers to anticipated frequently asked questions (FAQs) about the software. Full software details are given in the BSP programmer and API reference guides and performance characterisitics are given in the datasheet. Further recorded, the project goals to implement a subset of the POSIX.1 functions are identified through the EL/IX statement.

The dsp_K software aims to provide developers with a small real-time kernel and library that serves the embedded needs of DSPs. The project targets the Analog Devices (AD) 2106x "SHARC" family DSP core, but being written mostly in C it should be portable to similar cores. The software is tested using AD's 2106x simulator shipped with the VisualDSP development toolkit (version 2.2.0 and 2.2.2.2 as described in the about box, or CDROM version 4.0.1 and 4.1.2) and occasionally real hardware. Being fully configurable, it can run with application tasks entirely within on-chip memory. On-going development of the software is influenced by various Linux and EL/IX projects.

0.1 Version

This FAQ addresses the software snapshot version 0.6. The software version is maintained in the file dsp_K/sys/version.h.

1. General

1.1 What is dsp_K?

The dsp_K software is an embedded real-time kernel and library for DSPs. It consists of configurable library of sources to be linked with applications that can then be booted onto target hardware. The software is a task-based kernel that supports applications designed using tasks, schedulers and inter-task communicators. Applications are statically configured and linked with the kernel board support package (BSP) and an application programming interface (API), along with any required device drivers and libraries, to provide a well-known function within well-known memory constraints.
1.1.1 Open source
Like all Open Source, the dsp_K software is copyright and not in the public domain. It is open source as described in the license.
1.1.2 How is it pronounced?
The name is pronounced dee-ess-pea-kay (no surprise there then). Punctuation can be used to vary the tone and the use of smileys e.g. dsp_K:-) is fun so that is encouraged. There is a good book from O'Reilly about smileys (see http://www.oreilly.com/catalog/smileys/).
1.1.3 What are the project goals?
In addition to providing high quality development software, the project goals include helping to extend the scope for use of open source into embedded systems. It is now well-recognised that Linux is making significant in-roads into the embedded microprocessor arena, but not on DSPs. By providing an EL/IX statement, the dsp_K project is looking for reasonable compatability with Linux at the application level. However, the project also seeks compatability with commercial real-time systems such as vxWorks and it targets commercial developers. This hybrid set of goals is captured in the license, which allows a mix of open and closed source elements within a dsp_K system.

1.2 Why use it?

There are several reasons why dsp_K might be used, following.
1.2.1 Why use a kernel at all?
Principally a kernel like dsp_K provides a way to organise an application program. Often what is designed to be an efficient DSP function evolves into one that is less so as new requirements are added. A kernel does have runtime overhead, but a kernel-based application is configured to satisfy various design criteria and furthermore use of a kernel allows for future additions or reuse. Often, applications can also be ported to new hardware more easily, or in the case of dsp_K through its POSIX-like libraries can integrate more easily with other microprocessors in a broader computer hardware system.
1.2.2 Why would organisations use it?
There are a number of technical reasons that organisations might choose to use dsp_K. Here are some:
  • developers are able and encouraged to modify the kernel for their own benefit
  • project development is aiming to provide an EL/IX subset of POSIX.1 where it makes sense for DSPs
  • only required elements of the kernel, drivers and libraries are linked into the executable
  • the kernel is both configurable and scalable at buildtime through a single application configuration file
  • it is easy to program runtime flow control through developer supplied schedulers (round-robin and priority schedulers are provided)
  • applications are task structured and therefore readily familiar to real-time programmers
  • the software is layered from a common kernel BSP, APIs, device drivers and (POSIX.1-like) libraries
  • technical support should be found freely through Internet newsgroups, especially as existing Linux code is ported across
    • There are a number of business reasons to consider using dsp_K, including:
  • the software is licensed open source and protected through copyright law (see DeBona below for papers concerning business and open source)
  • the software license permits private use without requiring proprietary interests to be surrendered
  • it is never required that private software be made open source, should people not wish to do so it can remain closed source
  • in the main, the license requires only that details of the open source kernel used be identified and recognised
  • the license permits royalty-free public or commercial re-distribution
  • the software is a good candidate for both prototyping and distributing applications
  • the software gives you control and management of your application (it's your computer)
  • there is no marketing hype, what you see is what you get
    • There are a few business reasons for not using dsp_K:
  • the software is neither certified (safety critical etc.) nor comes with any warranty
  • there is neither paid support nor help desk to tell you when to reinstall or upgrade (third parties may offer service)
    • 1.2.2.1 What does Open Source do for business?
    Simply put, open source software gives its users rights to copy, investigate, modify and redistribute. Unlike proprietary software, open source neither locks users into some vendor's direction nor into a private maintenance nightmare (such as when your custom kernel key developer takes another job or when your O/S supplier no longer supports the version you have).
    1.2.2.2 How does Open source make money?
    Eric Raymond (a well-respected open source advocate) identifies several business models by which money is made using open source (see DiBona below).

    More generally, money is made by marketing products and services, not by the software needed to make them work. Even the best supported closed source kernel providers, like WindRiver, have on occasion to say they cannot supply a timely answer or fix and your product quality or design may suffer consequently. Open Source would help engineers with quality and timely control of custom designs and maintenance, leading to better organised marketing and service.

    Oftentimes developers are motivated when working with open source because it provides a sense of longevity of their efforts beyond the scope of their current project. They invest effort in getting it right because their software goes on public display and quality is often high.

    1.2.2.3 But many proprietary vendors offer source code
    Yes, but try changing it and then asking for support. Among the first things the vendor will likely ask is which version you have and will furthermore unlikely be able to support your changes. Open source gives its users the right to make changes and to feed those changes back. Sources fed back can assign copyright either to the project maintainer which is simply easier or to the provider - it doesn't really matter as long as someone asserts copyright.
    1.2.2.4 But anyone can easily take it
    Well, that is the whole point. People can't steal open source software because it is both readily available and under copyright license. The worst that can really be done (and surprisingly often is) is that the software is used in a way that contravenes the license. But then such use goes unsupported and the code becomes out of date fairly quickly. There just isn't really any point in following such a route; perhaps people imagine they achieve a short-term jump to get a product out the door, which then has to be supported and your key developer moves on....
    1.2.2.5 But my competitors benefit from my contributions
    How exactly? The dsp_K kernel is open source (and available to anyone) but your application software may remain private should you wish it. You would quite happily use a proprietary kernel, such as vxWorks, and so do your competitors. Goto 1.2.2.1 (yes goto statements are allowed in open source :-)....

    These brief things said, open source can be novel to grasp; see DiBona (below) for a detailed exploration.

    1.2.3 Why would an individual use it?
    Individuals might use it from interest or to help with a small project:
  • as one means to study kernels on DSPs (less resources than microprocessors) and the hardware too
  • as a way to share with the open source community, or to see how bits of Linux can be migrated
  • as a basis for low-cost software projects, academic works or as a hobby
  • as a stepping stone before getting into an advanced micro-kernel, such as Mach (which some Linux systems build upon)

    • 1.3 Where is the license?

    The dsp_K source set is shipped with a license in the file dsp_K.lic. This license is formatted as a C language comment and is included by source files in the distribution. It also applies to the documents in the distribution, of which this FAQ is one (others being the programmer and reference guides and the datasheet). The license is in the spirit of open source and aims to encourage both distribution of and open access to full source code, but to protect private interests. To achieve this aim, it is based upon the GNU Lesser General Public License (LGPL) but includes modifications. (Please note Linux is GPL and care should be taken when 'inheriting' code if proprietary concerns persist. The libraries distributed with dsp_K are almost wholly rewritten with no lien unless stated.)
    1.3.1 Other licenses
    The dsp_K license allows developers to choose GNUs LGPL should they wish to do so (through term 3) as described in a HOWTO. While this author believes the license supplied is superior for dsp_K, potential users may be more comfortable giving up some reliefs offered by it in order to use a more established license. Refer to both the dsp_K license and below for a discussion and also to GNUs web site.

    1.4 How is the software used?

    The dsp_K software is a development suite: it is unlikely users can just point, click and go. Anyone is able to use it, however, the intended user profile targets DSP software developers. Using dsp_K the developer will first try out the distribution to get the examples running in the simulator, perhaps also trying them on target hardware by making small modifications to flash LEDs or similar. Next, the developer may decide if the software will fit a particular job, weighing various technical and commercial benefits including open source code against the lack of paid support.

    1.5 Who supports the software?

    The dsp_K software can be supported by a user community on the Internet where questions and bug reports can be raised on appropriate Internet newsgroups, such as comp.dsp and comp.arch.embedded. Anyone may offer paid support for open source software (but they cannot charge you for the software itself); the license provides such benefits. You can email this author, but timely support is unlikely to be available. Developers should be prepared to work from the sources considering dsp_K as part of their application being developed. Use of dsp_K or open source doesn't affect tool support (e.g. from Analog Devices for VDSP).

    Unlike proprietary vendors, the dsp_K project does not need to make money to survive. While contributors may come and go, all open source software will persist. The same cannot be said of proprietary software (such as PSOS being phased out by vxWorks).

    1.6 What hardware and resources does it run on?

    The kernel runs on the AD 2106x (SHARC) family. An accompanying datasheet provides runtime and build size statistics for the kernel on the AD-21065L using AD's VisualDSP version 2.2.0 (CD 4.0.1) or 2.2.2.2 (CD 4.1.2) development tools. Currently, a small build uses about 1.5K of code words and about 0.2K of data words, comfortably into on-chip memory.

    1.7 Where can I find the software?

    The software is available on the Internet at http://www.jhrose.dial.pipex.com/dsp_K.htm (remember the underscore in dsp_K). It shall hopefully be made available through the popular open source site sourceforge, for which efforts to get the project structure set up continue :-)

    1.8 What books are recommended?

    Apart from this FAQ, the programmer and reference guides and datasheet, there are no manuals for dsp_K. There are many good books on kernels and real-time programming available, no specific recommendations are made. It is very useful (even essential) to have copies of the relevant hardware manuals, e.g. SHARC document set.

    For general reference the author owns:

  • Open Sources. DiBona et al, O'Reilly, 1999.
  • Linux Kernel Internals. Beck et al, Addison-Wesley, 1996.
  • Occam reference manual. Inmos, Prentice-Hall, 1989.

    • 1.9 What Internet resources are useful?

    Relevant web sites include:
  • SHARCpage (new revised edition)
  • EL/IX (Cygnus site for embedded POSIX.1 Linux)
  • RTLinux (for host processor interfacing; see rtl_fifo driver)

    •  

     
     
     
     
     

    Relevant newsgroups include:

  • comp.dsp
  • comp.arch.embedded

    •  

     
     
     
     
     

    See also the list of links from the project home page.

    2. Kernel

    2.1 What is the kernel exactly?

    The dsp_K kernel is a task manager and central switching function, which aim to have the most important task running at any time. The kernel BSP consists of a library of functions that are statically linked with applications and an available API along with any device drivers or library functions to produce bootable programs for loading onto the target hardware.

    Application tasks participate in switching through use of programmer-provided scheduler functions. Several scheduler functions can reside within the one application and be invoked by different application tasks. The kernel provides a PIT (periodic interval timer) function that can be enabled or disabled, and when run invokes the scheduler function of the current task. By default, the PIT function is enabled.

    2.1.1 What is meant by the most important task?
    The scheduling algorithm is the heart of the kernel. Kernels traditionally use a static priority or a round robin algorithm to select a task, which is then supplied to the task switcher code if necessary. With dsp_K, an application includes programmable schedulers to determine which task is run; the current task selects which it wishes to have run next. Therefore, dsp_K requires the application writer to program scheduling (default priority and round robin functions are provided).

    2.2 What does the kernel do?

    The kernel provides a minimal set of integrated services, which have been developed especially to meet the needs of DSP architectures. Specifically such needs are those of small resources and real-time performance. Consequently, the kernel lacks many features normally found in higher specification microprocessor kernels, e.g. support for file systems and networking.

    The kernel model allows the application developer to concentrate on both modular software and hardware interface design and to separate out program flow control. The 4 key concerns of dsp_K application design are:

  • the tasks for data processing
  • device drivers (and libraries) for data i/o and high level functions
  • scheduler functions
  • inter-task communication (including host processor interfacing)

    • 2.3 How is the kernel configured?

    The kernel is configured per application through the dsp_Kcfg.h header file, which supports a range of settings (see also the dsp_Ku.h file). Each application will include its own version of this file, with #defineDSP_K_NUM_TASKS for example. Configuration is achieved by setting values for each of the available preprocessor definitions, mostly to 1 to enable or to 0 to disable features. The available settings are described in the programmer guide.
    2.3.1 Tool settings
    In addition to AD toolkit settings, the variable VDSP_VER must be defined for the toolkit used. It is defined to 401 for VDSP 4.0.1 or to 412 for VDSP 4.1.2. (Please note, this author is no longer able to check builds for the 4.1.0 or 4.1.1 releases, although it is pretty much known when changes will impact these versions. Future changes may require developers upgrade to version 4.1.2. or later.) (Neither newer versions nor VDSP++ have been tried, although others report they seem to work with dsp_K.)
    2.3.2 Configuration catches
    Even when a configuration builds, it is necessary to ensure consistent settings in order to prevent strange runtime behaviour. As with all modifiable programs, it is possible to build a kernel that will fail to test successfully, although it may be functionally correct. For example, too high an interrupt rate for the PIT may exceed the practical limits of some systems. Writing to non-existant memory also produces odd runtime behaviour (there is no MMU to raise a bus fault on a SHARC itself, an external device would be required).

    2.4 What is a task?

    Using dsp_K application software is arranged as a collection of tasks, each of which comprise ordinary C data and functions. (Assembly code can equally be used, there is no difference to the kernel.) There are neither special declarations nor any special source text requirements. Tasks should be placed in a separate source file(s), along with a program main entry point, and these compiled and linked with the kernel sources. Each user source file should reference the required API (e.g. #include "monolith.h") to obtain kernel function prototypes and configuration definitions (dsp_Kcfg.h is #included by monolith.h).
    2.4.1 How are tasks started?
    A task is identified by naming it in the task control block, which is passed to DSP_K_RUN to start the kernel running from the main program. Once all tasks have exited or are blocked, the kernel returns to the main program.

    2.5 How do tasks communicate?

    Tasks can communicate through synchronous (shared data) messages or channels and asynchronous (shared memory) semaphores and signals. The mechanisms available are a feature of the chosen API. (Of course, tasks can access global shared memory too which is flat on the SHARC.)
    2.5.1 Synchronous Messages
    A task wishing to send a message and finding the receiver busy will be suspended. Similarly one wishing to receive a message and finding no sender waiting will block. Either a sender or a receiver wishing to communicate and finding it possible will do so and cause the corresponding task to be made ready for scheduling. After communication, the kernel will run the current object scheduling function.

    One task may send a message to another, or wait until it can receive another sent to it. Such exchanges are synchronous and provide scheduling points. A task wishing to send and finding the receiver unavailable will be suspended. Similarly one ready to receive and finding no available message will block. Otherwise, the sender and receiver tasks will both be awakened to exchange data. After communication, the kernel will run the current task scheduling function.

    2.5.2 Synchronous Channels
    Using the process API, tasks communicate through point-to-point channels. One task may output data to another, or wait until it can input data sent to it. Such exchanges are synchronous and provide scheduling points in software.

    A task wishing to output and finding its recipient unavailable will be suspended. Similarly one wishing to input and finding the channel empty will block. However, a task wishing to communicate and finding a channel full, will engage in data exchange and awaken the far end-point task. After communication, the kernel will run the current task scheduling function.

    2.5.3 Asynchronous Semaphores
    Using the monolithic API, both shared data and shared memory may be used. For example, a global variable may be accessed by more than one task, in which case access to it might be protected through use of the monolithic API semaphore functions. Using shared memory this way removes the 'memcpy' incurred in a message exchange.

    Signals have been added to dsp_K through a device driver and support libraries. Tasks call POSIX-like library functions to manage their signal permissions and to send signals to each other.

    2.5.4 Shared memory
    Shared memory, or global variables, can be used with dsp_K (because the memory model is flat). The same can be corrupted :-)

    2.6 How is hardware accessed?

    Device drivers may be included in an application to manage control of some hardware or interface to the software system. Device drivers are parts of the application software to be provided by programmers and provide a wrapper for managing hardware interfaces and for interrupt management. Applications may attach interrupt service routines (ISRs) to device drivers and enable or disable hardware interrupts.

    A number of drivers are provided, although there is little support for the on-chip SHARC devices like DMA and SPORT, simply because I have never needed to use them. (My current development platform, WWG2262, features two 21065 arranged in a cluster and external SRAM provides their interface.) You could use a SPORT fairly easily, to connect with a serial port attached with a console or debug engine...

    2.6.1 Register external connections
    Some DSP registers are tied to external hardware, like the ASTAT & MODE2 registers on the SHARC are tied to external FLAG pins. The kernel should generally preserve the states of these register settings across all tasks, but it is possible to modify the kernel sources to do otherwise. At startup, the kernel programs these registers with values supplied during configuration.

    2.7 How to test programs?

    The easiest way to develop and test dsp_K applications is currently to use the VDSP simulator. Although the SHARC simulator can exhibit buggy behaviour (the 4.0.1 simulator is somewhat 'lazy' about taking interrupts amongst other bits of detail), software that runs there should run equally well on real hardware.

    When target hardware is required to be used and tested it is a matter of project requirements, but maybe generally easiest to attempt progress stepwise and perform a bottom-up test rather than throw the system into the deep end and perform a top-down test. The full range of AD and third party tools and emulators can be used with dsp_K software systems.

    2.8 What else might developers need to know?

    There are some features of the kernel which are not configurable, short of re-programming.
    2.8.1 Stack checking
    The kernel performs runtime stack checking on a per task basis. (Unfortunately, the SHARC does not make it possible for the kernel to trap illegal memory accesses, although the VisualDSP simulator/debugger can do this and can be used for application prototyping.)
    2.8.2 Signals and interrupts
    The dsp_K fast interrupt method is recommended, but you can use the C interrupt routines (e.g. signal, raise). It is not completely possible to support nested interrupts using this fast interrupt method (because the shadow registers are used), but nested interrupts may be enabled (through the DSP_K_NESTED_INTR configuration variable) if it is known that higher priority interrupts will not pre-empt a running ISR through the DSP_K_INTR_RAPPER entry point in dsp_Khdr.asm.
    2.8.2.1 What are fast interrupts?
    Fast interrupts are used in the dsp_Khdr.asm interrupt vectors with dsp_K, so called because not all system registers are context saved by default. The VDSP interrupt wrapper on the other hand saves all registers. Choosing which registers to context save is achieved by modifying parameters in the configuration file, dsp_Kcfg.h.

    2.9 What developments are in the pipeline?

    Generally the kernel shall aim to support an EL/IX subset of the POSIX functions where it makes sense for DSPs. (Guidance has been taken from Cygnus on a suitable EL/IX profile and remains open for thought.) Refer to the dsp_K Internet home page to see what specific developments are current.
    2.9.1 Is dsp_K Linux for the SHARC?
    No, Linux is a kernel copyright Linus Torvalds, the richness of which exceeds the useful capability of DSPs in this author's opinion. But dsp_K aims to be Linux friendly, which means a Linux system can provide host services for dsp_K and suitable Linux (POSIX, EL/IX) applications should be fairly easily ported. Similarly, a commercial RTOS such as vxWorks might provide host services for dsp_K in an embedded application. Through a POSIX-like interface, source code or headers might even be shared with a host processor.

    3. Build Time

    3.1 VisualDSP 4.0.1 and 4.1.2 currently supported

    Currently this author has access to the AD VisualDSP development toolkit for the AD-2106x SHARC family. The dsp_K software has been mainly developed using the 21065 (baby SHARC) simulator and has been tested both on this and real target hardware. CD-ROM versions 4.0.1 or 4.1.2 featuring the AD cc21k compiler are used (but there is no particular reason why the software cannot be ported to the GNU version of the SHARC tools with a bit of effort).

    This author can test only VDSP version 4.0.1 and 4.1.2, so users of 4.1.[01] should consider themselves on borrowed time (since any changes to DSP_K_SWITCH cannot be tested). Users of 4.0.1 should consider upgrading to 4.1.2. Other people have successfully tried using later tools and the newest VDSP++ toolkit in C mode. C++ should work in principal, especially as VDSP++ uses a source-level front-end preprocessor. Personally, I think C++ is kind of heavyweight for writing efficient DSP programs, but each to their own opinion and I've never tried :-)

    3.1.1 Building for 2106x
    The kernel must be built to target the different 2106x family members. The steps to target a specific CPU are:
  • Modify the SHARC configuration variable in dsp_Kcfg.h to one of the four available settings
  • Select the appropriate VDSP project options, project tab and loader tab settings and define VDSP_VER
  • Include an appropriate linker directive file (.ldf). Four files are supplied as examples, for each of the 21060, 21061, 21062 and 21065L
  • Rebuild-all
    • Linker errors may have crept in during minor versions (0.x.y), since my testing normally ends on 21065 on the simulator, so if the build fails to link then try modifying the sample .ldf files. If the include files can't be found during compilation, then change the settings in the project options include settings for the compiler and assembler; older versions used quotes and commas where newer versions of the tools use semi-colons etc.
    3.1.2 Porting the kernel
    There is nothing in particular that would prevent dsp_K being ported to similar DSP architectures (or low-specification microprocessors), and by this it is meant similar register sets and flat memory models. The kernel requires a program counter (PC), frame pointer (FP) and stack pointer (SP) but nothing else especially. The kernel does simple tricks with the condition register (ASTAT) and stack checking registers. It is necessary to think carefully about nested interrupts (MODE1) register because the "fast interrupt" method replaces the C library by using shadow registers. Developers are advised to study the code for a few days or try it on the VDSP simulator if possible to learn how the kernel works and where its tricks lie.
    3.1.3 Porting applications
    As the EL/IX or POSIX library grows it should become easier for people to port existing applications to dsp_K, or conversely from it to other systems. The latter might be useful when using dsp_K or a SHARC to prototype. This author generally writes small Linux programs on a PC and then ports them to dsp_K.
    3.1.4 Host processor interfacing
    Using POSIX-like functions in dsp_K make developing applications for a multi-processsor board easier since the API is familiar. It is possible to interface with a host processor running vxWorks for example across shared memory (as this author has done). The rtl_fifo device driver provides one mechanism to support this.

    3.2 VDSP warnings

    This option (run automatically by VDSP when a project is opened) checks all the files required for compilation of each source identified in the project folder and will complain if it cannot find a file. You should be able to add entries to the include directive for the compiler and the assembler using the project->options menu item. Regardless, performing a project->rebuild all bypasses any dependencies calculated.
    3.2.1 The compiler complains about sig_glob.h
    This file is found in c:\programs\analog devices\VisualDSP\21k\lib\src\ (or similar) and is included by _dsp_K.asm for use in the interrupt vector table. You could amend the VDSP project->options->assemble dialog value to add this directory on the include path.

    3.3 The compiler complains about monolith.h

    Generally, you will need to include its directory location on the compiler include path. Modify the VDSP project->options->compile->preprocessor additional include directories dialog.

    3.4 The compiler uses the wrong dsp_Kcfg.h

    This problem is similar to 3.3 above, but there will be a separate version of this file for each application. The configuration file (dsp_Kcfg.h) is used to store the project configuration data for the kernel per application. Generally, the project configuration file should be kept in the project directory.

    3.5 The cc21k front-end complains about an unbalanced symbol table

    This can happen when the _KCO_ (kernel code) segments are in a different location to the normal program code (seg_pmco) segment. A kind reader on the comp.dsp newsgroup said to disable Generate debug information on the VDSP project->options->compile dialog, which cures this. (I do not know why this happens, could be an a21000 assembler bug :-) Nevertheless, this fix can make life difficult during kernel development so _KCO_ is often commented out (C++ style).

    You can safely comment out the _KCO_ or _KDA_ usage and have the kernel code share segment space with normal program code or data.

    3.6 VDSP IDE crashes on startup with an illegal instruction

    This is likely caused by an incompatibility between a Visual C DLL and VDSP and can happen on both Win95 and WinNT. There is an executable compressed file, speu.exe, shipped with VDSP which when run replaces a number of system DLLs. The AD help desk (White Mountain) may tell you to reinstall on a WinNT patch level 5 system, but that has been known to crash too. (Also the custom install option may not work properly, instead try the full installation.)

    3.7 What STACK_SIZE should be assigned to objects?

    The level of nested function calls, interrupt levels and the local (automatic) variables used by each function determines its STACK_SIZE; this can be calculated, but will vary for every task and so a general value cannot be provided. That said, a starting point of #define STACK_SIZE ( 0x100 ) as used in the generic examples seems reasonable.

    4. Run Time

    4.1 The VDSP simulator crashes

    When this happens, try deleting the file(s) in c:\programs\analog devices\VisualDSP\data\, ADSP-2106x Simulator SHARC Debug Target Component Data. You will then need to re-open your saved .layout file to recover the register windows etc.

    4.2 The program crashes with interrupt underflow

    This occurs when a rti instruction is executed but the pcstk register is empty, normally at the end of the interrupt wrapper in _dsp_K.asm, or perhaps in an errant interrupt handler. Open the appropriate register windows in the simulator and inspect the state. Trace back up the current task stack to see where the program was when this error occurred.

    4.3 Linker errors

    4.3.1 Linker says "Memory segment 'seg_krco' needs n more words"
    This occurs when insufficient memory has been allocated for the segment seg_krco in the .ldf file. You will need to provide more memory for the segment, or move the segment to a different memory bank (e.g. off-chip) if there is insufficient available.
    4.3.2 Linker says "Memory conflict for memory <segment name>"
    This occurs when the memory configuration in the .ldf file cannot be mapped onto the target hardware. Compare your settings with the example linker files supplied, or better yet refer to the VDSP manuals on the various architecture memory permutations permitted.

    4.4 How to report a suspected bug?

    To report a bug you could post to an appropriate newsgroup or the project maintainer. Being able to reproduce problems is important as they can be time consuming and difficult to understand and are usually dependent upon an exact set of circumstances or chain of events. Ask others to assist, but truly, the best approach is to spend the time getting to know the code and to post a fix.
    4.4.1 Where to start looking?
    Assuming code is being run in the simulator (be thankful you can rule out hardware problems :-), firstly take a dump of the state: write down register values, parts of the task stacks and kernel task switch saves. Secondly, work out what actually caused the error, e.g. register i12 points to 0x0 or some other illegal code memory address. Thirdly, try to reproduce the error and the steps leading up to it. It may take several hours or even a couple of evenings getting to this stage, be patient.
    4.4.2 State dump hints
    A useful state dump includes the kernel data, register values and task stacks. If the faulty program is run using "out of the box" configuration then the kernel parameters are found at 0x9e00 downward (in fact this is described as a comment within dsp_K.c) and the task stacks and data are found at 0xc000 downward (tasks, channels or messages and stacks); stacks grow up. Data structures for objects and channels at this address are found in the BSP dsp_K.h and monolith.h or process.h API header files.
    4.4.3 Repetition hints
    If the number of CPU cycles is reasonably short (see LS register), then try re-running until shortly before and try to spot where the fault occurs and what looks unexpected. Setting watchpoints is often useful at these times.
    4.4.4 Likely hints
    It is likely a task stack is corrupted (or incorrectly restored), often showing up when i12 points to an illegal address. This could happened if DSP_K_SWITCH should fail, but can also happen when errors with local variables occur. If your program is getting large, check that enough stack space is allocated.

    5. License

    5.1 Why not GPL, LGPL or BSD?

    A lot of thought has gone into choosing which license to apply to dsp_K. The license has to satisfy the requirements for several seemingly conflicting needs: to encourage free software or open source, but protect private or proprietary interests; to allow source code re-distribution but preclude public contributions being turned into proprietary works; to balance a legal copyright with support for a creative and open spirit. In addition, dsp_K will likely be used as part of some embedded system and so a binary distribution would differ from free software like PC-based GNU/Linux.

    The GNU General Purpose License ("GPL") could not be used because it precludes linking with private libraries, e.g. AD VDSP C library. The Berkeley Software Distribution ("BSD") license allows anyone to redistribute binaries and this would seemingly conflict with proprietary interests. There exist various other licenses and in studying them one rapidly becomes embroiled in semantics and the possibility of having to make compromises.

    While several other open source licenses were in fact reviewed, the best known while being very close to satisfying the requirements is the GNU Lesser General Purpose License ("LGPL"). However, the right for users to reverse engineer binary distributions of LGPL software presents certain problems, and that, coupled with the generality of its terms, meant it was decided not to use the LGPL. Rather the LGPL was chosen as a foundation to apply dsp_K-specific modifications.

    5.2 Why the attention to proprietary aspects?

    Unlike the widespread use of PCs and GNU/Linux systems for example, it is assumed that not many individuals have DSP systems at home to use. It seems clear that the majority of DSP users are likely to be found in proprietary industrial settings or academia and it is these people who are seen as the target audience.

    By writing a license specifically for dsp_K that is just as friendly to proprietary users as is the LGPL, but drawing attention to proprietary concerns as much as to free software, it is hoped that potential users of the kernel shall give good consideration to using the software where otherwise they might avoid doing so for lack of understanding the LGPL. It is worth quoting from the license preamble: [users] MAY MAKE AND KEEP PRIVATE CHANGED SOURCES. Further [users] MAY LINK WITH PRIVATE SOURCES and [users] MAY DISTRIBUTE BINARY, MODIFIED BINARY, LINKED BINARY OR EMBEDDED BINARY VERSIONS OF THE KERNEL having only to publicise any source changes to dsp_K itself.. This is in fact wholly compatible with the LGPL, but rather special attention is drawn to it here.

    5.2.1 Special notice on clauses
    In modifying LGPL to produce the dsp_K license (apart from rewriting terms 13 and 14 completely) distinct changes have been made to items 3 and 6 of the terms and conditions, because there remains some small doubt about how the LGPL could be interpreted.

    In clause 6 the right to reverse engineer works linked with the kernel is removed and instead included is the right to re-link such works with a modified version of the kernel, for private use. This has been done to better clarify users rights as applied to embedded distributions; if distributors make it technically possible to modify embedded works through users re-linking their (proprietary) application object code with optionally modified kernel software, then the requirements are satisfied. That embedded work may be separately copyright or subject to a proprietary set of terms that forbid reverse engineering.

    In clause 3, we offer users the option to apply the LGPL terms and conditions instead of the dsp_K license, but only to distributions of the kernel where no other software has already been linked. In this way users have all the rights expected with free software for the kernel, but we forbid clause 6 of the LGPL being invoked on (private) works linked with the kernel (which could be done once the terms have been changed).

    5.2.2 Special notice on contributors
    Both Eric Raymond and Richard Stallman provided much kind assistance, time and guidance in drafting the dsp_K license. Yet it might not fairly represent their opinions, rather the terms and clauses are our own. Furthermore, nothing should be assumed about dsp_K itself having any recommendation or endorsement or other relationship with these individuals nor the organisations with which they are involved.

    5.3 A libertas interpretation of terms and conditions

    This section provides plain language or common usage descriptions for each of the 17 terms and conditions found in the dsp_K license. You should take these only as a guide to understanding the terms and conditions and their aim is to clarify any potential  misunderstanding. Further, the preamble in the license itself attempts to set out the aims of the license.
    5.3.0 Term of terms
  • This term defines the terms used throughout the remainder of the license.
  • It also identifies the license scope, which is limited to copying, re-distributing and modifying the software.
  • The source files to which the license applies are identified, and they include program source files and document source files.
  • The means to identify the licensed sources and possible future additions to the source distribution is also given.
  • It also identifies related source files that are not covered by the license, and each will be copyright or public domain or possibly covered by some other license.
  • A "work that uses the Software" would include, for example, a device driver or application code.
  • A "work based on the Software" would include an embedded binary or a new version of the kernel or a port.
    • 5.3.1 Term of source distribution
  • This is about your main rights as a user of the software, to obtain or copy the source code and to re-distribute it.
  • It says what you must do if you choose to re-distribute the sources and the notices you must provide.
  • It also identifies how you may run a business operation, for distribution and support services.
    • 5.3.2 Term of source modification
  • This term covers your further rights to modify the source software you receive.
  • It says what you must do should you choose to re-distribute your modified source software.
  • You may keep your modifications privately, that is there exists no requirement to re-distribute your changes.
    • 5.3.3 Term of license
  • This term explicitly allows you the option to re-license the software using LGPL under certain circumstances: you may apply the LGPL to the dsp_K kernel and only the kernel.
  • You may not apply the LGPL to modified software or derived software, unless it is already LGPL, even if you have extended the kernel significantly.
  • In general, if you are a devotee of free software then you will probably opt to apply the LGPL.
  • In general, if you have private or proprietary interests then you will probably be less likely to opt to apply the LGPL, unless you are happy with its terms. In short, you would give your users the right to reverse engineer your software by applying the LGPL.
  • You may, however, use software that has other licenses applied together with the kernel inasmuch as they permit.
    • 5.3.4 Term of binary distribution
  • This term permits you to re-distribute your (embedded) application programs that use the kernel.
  • It says what you are required to do, which is to make the licensed kernel sources available. This can be, for example, on a floppy disk or on your Internet ftp server.
  • If you haven't modified the kernel sources, it would be acceptable to identify either the place from which you obtained your copy or a well-known Internet site.
    • 5.3.5 Term of derivation
  • This term explains how a "work that uses the Software" becomes a "work based on the Software". Such a transition invokes the dsp_K license.
  • Basically, any form of software that includes the kernel, source or object, irrespective of how that is stored e.g. on disk or in ROM, is a derivative.
    • 5.3.6 Term of proprietary distribution
  • This term merits special attention by proprietary users of the kernel.
  • It says what you are required to do if you re-distribute a derived version of the kernel, e.g. an image in FLASH or an executable on disk.
  • Basically, you must allow users the capability to create a new binary or executable by linking a (modified) kernel with your object code.
  • You do not have to provide the means to do this, i.e. you do not have to supply any software development tools.
  • You may have a separate license that forbids any reverse engineering of your object code. No user has the right to your private software investment unless you give it, but they have the right to modify the kernel and to apply such modification with your private software for their own use.
  • Users do not have the right to redistribute your derived distribution nor one they modified as above, unless you separately give permission.
  • Users do not have the right to, e.g. re-FLASH any hardware you supplied them, unless you separately give permission.
  • You may satisfy this requirement with a loose control, e.g. put your object code on an Internet ftp server.
  • Alternatively, you might use a strict control, e.g. require a form be completed and signed which grants appropriate terms of use or license before granting users access to your object code. This is a method used by several proprietary vendors, e.g. Palm computing with the Pilot ROM software.
    • 5.3.7 Term of aggregation
  • This term explains what you must do to re-distribute a derivation of the kernel (e.g. an application) together with other software.
  • This would apply if the kernel was used as part of some package or suite of tools.
  • It would also apply if you just want to pass on a floppy disk to your friends.
    • 5.3.8 Term of social behaviour
  • Other people have been kind to provide you with the kernel software sources, or perhaps device drivers. This they did knowing the terms that apply.
  • You are required to play by the same rules as others, to copy software under the terms they gave it to you, whether they gave the software to you directly or indirectly.
    • 5.3.9 Term of legal contract
  • The license is a contract you are not required to accept e.g. if you received a copy of the software but do not want to use it. If so, you can archive the software for some later time, or just delete your copy.
  • Copyright law both protects the software and is that which the license is subservient. The law applies to the software at all times.
    • 5.3.10 Term of freedom
  • If you choose to re-distribute the software, you must also pass on the same freedom as you received.
  • You cannot remove the rights you received or deny them to others.
    • 5.3.11 Term of society
  • This is a term of litigation for the lawyers and any ruling passed on your use of the software in society.
  • Nevertheless, it is also a term that supports the free software movement and the open source movement. You might make the effort to understand these two movements to which you participate and how they work in society.
    • 5.3.12 Term of internationalism
  • The software is distributed via the Internet and therefore crosses International borders.
  • This item gives the copyright holder permission to change the license after the software has been distributed, but only if some law makes that necessary. It would be unusual and require the copyright to justify such action by reference to the law or ruling or cause recognised at government level.
    • 5.3.13 Term of aims
  • The term "open source" implies a trademark that has not been sought.
  • While the kernel can rightly be considered open source, it may be that some (future) definition is incompatible.
  • However, you should assume dsp_K shall remain open source: the kernel cannot suddenly become proprietary software.
  • You might also adopt "open source" or "free" software as an aim in your work, but it is your choice.
    • 5.3.14 Term of contribution
  • The point of making the kernel free software in the spirit of open source includes our asking for your help to support, maintain and grow the software.
  • However, you have no rights given to you regarding support (unless you purchase them separately from a third party).
  • It is hoped that users shall contribute device drivers and modifications or co-routines for the kernel to the official distribution, and in return they shall receive public credit.
  • Users should expect some support in contributing to the official distribution and it is explained what you should expect.
    • 5.3.15 Term of warranty
  • The kernel is distributed without warranty.
  • This does not mean it is of low quality; in fact it is widely believed that the more people who use open source software the higher its quality should become (by bug fixes and new capability).
    • 5.3.16 Term of indemnity
  • You use the kernel at your own risk and cannot assume anyone else is responsible for any failure that results in your choosing to do so.
  • It is not stated for what purpose the kernel can, or cannot, be used for.
  • The kernel is not certified nor approved to any standard, especially not for any safety critical use.

    • 5.4 Is dsp_K open source?

    In a word, yes. However, to date, no attempt has been made to have dsp_K software certified as "open source". In fact, we avoid labelling dsp_K "open source" because it implies a trademark that is not possessed; this decision affects our use of the term rather than our aims. Similarly, dsp_K is not labelled "free" software as defined by the Free Software Foundation (FSF), although we actually aim to satisfy all four kinds of freedom that would qualify us; this too affects our use of the term (and influences our choice not to apply LGPL) more than our aims. Rather, in a somewhat diplomatic fashion, to convey our intention we say dsp_K is freely available in the spirit of open source.

    The dsp_K license aims for full LGPL compatibility and aims to be open source. To really answer the question we have to check each point made in the open source definition, published by Bruce Perens and available at http://www.opensource.org/osd.html, and comment on the dsp_K license.

    5.4.1 Free redistribution
    There is no restriction on redistribution of the dsp_K source software or as a component of a binary distribution. No royalty is chargeable on the dsp_K software.
    5.4.2 Source code
    All distributions in whatever form are required to state clearly which base version of dsp_K has been used and from where the base source may be obtained on the Internet.
    5.4.3 Derived works
    Anyone may make changes to the dsp_K software and is permitted to make those changes public. The dsp_K license applies to modifications of the kernel source files; users may also opt to apply the LGPL under certain circumstances. The dsp_K license says nothing about source code outside the kernel source files, which may be covered by a separate license.
    5.4.4 Integrity of the Author's source code
    Changes may be kept private, but if redistributed (in binary or embedded form) it is required that a suitable statement be made identifying that changes have been made and to which base version. It is also required that the modified source code be made available.

    The binary or embedded distribution may be under a separate (or commercial) license that prohibits redistribution. This would be normal is the dsp_K software was embedded in a commercial product, for example. In such cases, the dsp_K software must be made separately available.

    5.4.5 No discrimination against persons or groups
    The dsp_K license makes no discrimination on the user community.
    5.4.6 No discrimination against fields of endeavour
    The dsp_K license makes no discrimination on application.
    5.4.7 Distribution of license
    Use of the dsp_K software and documents are covered by the license. A copy of the license is included with all distributions (and compiled with the source code). Anyone may re-apply the dsp_K license to their own software if they wish (although it would make sense to delete the name dsp_K with whatever is appropriate, in the general case).
    5.4.8 License must not be specific to a product
    The dsp_K license is specific to the dsp_K kernel software, which may be used in any product.
    5.4.9 License must not contaminate other software
    The license says nothing whatsoever about software outside the dsp_K kernel sources and documents. The kernel may be aggregated with software under a different license and distributed on a single medium.
    5.4.10 Example licenses
    The dsp_K license is based upon the LGPL. It is clearly indicated herein where significant differences exist.


    Copyright (C) 2000-2001 Julian Rose, Sussex, U.K. This page is maintained by jhrose@dial.pipex.com.