PSP_User_Guide

i DM6437/C6424 DSP/BIOS PSP U s e r ' s G u i d e User's Manual ii IMPORTANT NOTICE Texas Instruments Incorporated and its subsidiaries (TI) reserve the right to make corrections, modifications, enhancements, improvements, and other changes to its products and services at any time and to discontinue any product or service without notice. Customers should obtain the latest relevant information before placing orders and should verify that such information is current and complete. All products are sold subject to TI’s terms and conditions of sale supplied at the time of order acknowledgment. TI warrants performance of its hardware products to the specifications applicable at the time of sale in accordance with TI’s standard warranty. Testing and other quality control techniques are used to the extent TI deems necessary to support this warranty. Except where mandated by government requirements, testing of all parameters of each product is not necessarily performed. TI assumes no liability for applications assistance or customer product design. Customers are responsible for their products and applications using TI components. To minimize the risks associated with customer products and applications, customers should provide adequate design and operating safeguards. TI does not warrant or represent that any license, either express or implied, is granted under any TI patent right, copyright, mask work right, or other TI intellectual property right relating to any combination, machine, or process in which TI products or services are used. Information published by TI regarding third-party products or services does not constitute a license from TI to use such products or services or a warranty or endorsement thereof. Use of such information may require a license from a third party under the patents or other intellectual property of the third party, or a license from TI under the patents or other intellectual property of TI. Reproduction of information in TI data books or data sheets is permissible only if reproduction is without alteration and is accompanied by all associated warranties, conditions, limitations, and notices. Reproduction of this information with alteration is an unfair and deceptive business practice. TI is not responsible or liable for such altered documentation. Resale of TI products or services with statements different from or beyond the parameters stated by TI for that product or service voids all express and any implied warranties for the associated TI product or service and is an unfair and deceptive business practice. TI is not responsible or liable for any such statements. Following are URLs where you can obtain information on other Texas Instruments products and application solutions: Products Applications Amplifiers amplifier.ti.com Audio www.ti.com/audio Data Converters dataconverter.ti.com Automotive www.ti.com/automotive DSP dsp.ti.com Broadband www.ti.com/broadband Interface interface.ti.com Digital Control www.ti.com/digitalcontrol Logic logic.ti.com Military www.ti.com/military Power Mgmt power.ti.com Optical Networking www.ti.com/opticalnetwork Microcontrollers microcontroller.ti.com Security www.ti.com/security Telephony www.ti.com/telephony Video & Imaging www.ti.com/video Wireless www.ti.com/wireless Mailing Address: Texas Instruments Post Office Box 655303, Dallas, Texas 75265 Copyright © 2006, Texas Instruments Incorporated iii Preface Read This First About This Manual This User’s Manual serves as a software programmer’s handbook for working with the DM6437/C6424 DSP/BIOS PSP Version GA 1.00.02.00 This manual provides necessary information regarding how to effectively install, build and use DM6437/C6424 DSP/BIOS PSP in user systems and applications. Abbreviations Table 1-1. Table of Abbreviations Abbreviation Description PSP Platform Support Package DM6437/C6424 DSP/BIOS PSP This is TI coined name for the product. API Application Programming Interface IOM Device Driver Adapter DDC Device driver core LLC Lower level controller OS Operating System PAL OS Platform abstraction layer for operating system SOC System On Chip Information About Cautions and Warnings iv Information About Cautions and Warnings This book may contain cautions and warnings. CAUTION WARNING The information in a caution or a warning is provided for your protection. Please read each caution and warning carefully. Related Documentation Internal This is a list of documents that are TI Proprietary and Strictly Private. Exposure to audience outside TI will need due considerations and approvals from TI Legal authorities. � DM6437 TRM and peripheral documents from PDS � C6424 TRM and peripheral documents from PDS Revision History Version Date Revision History 1.00.00.01 17th May 2007 GA Candidate Release 1.00.01.00 22nd June 2007 GA Patch release 1 This is an example of a caution statement. A caution statement describes a situation that could potentially damage your software or equipment. This is an example of a warning statement. A warning statement describes a situation that could potentially cause harm to you. v vi Contents READ THIS FIRST.................................................................................................. III CONTENTS................................................................................................................. VI TABLE OF TABLES ................................................................................................ VII TABLE OF FIGURES............................................................................................ VIII CHAPTER 1..................................................................................................................... I INTRODUCTION ........................................................................................................ I 1.1 Overview..................................................................................................... II 1.2 Driver Software Architecture ............................................................... II 1.3 Design Philosophy of drivers..............................................................VII CHAPTER 2................................................................................................................. XII INSTALLATION GUIDE ......................................................................................XII 2.1 Installation and Usage Procedure................................................... XIII 2.2 Un-Installation.......................................................................................XVI 2.3 PSP Component Folder .................................................................... XVIII 2.4 CCS Projects...........................................................................................XIX CHAPTER 3................................................................................................................. XX INTEGRATION GUIDE ........................................................................................ XX 3.1 Application Usage of PSP.....................................................................XX 3.2 Instrumentation Tool - SoC Analyzer usage ............................. XXIV CHAPTER 4............................................................................................................. XXXI RESOURCE GUIDE ............................................................................................XXXI vii Table of tables ABBREVIATION ...................................................................................................... III DESCRIPTION ......................................................................................................... III VERSION.....................................................................................................................IV DATE .............................................................................................................................IV REVISION HISTORY .............................................................................................IV Table of figures viii Table of figures FIGURE 1 TI DEVICE DRIVER FUNCTIONAL DECOMPOSITION........................................III FIGURE 2 GENESIS OF PAL-OS................................................................................... VII FIGURE 3 MONOLITHIC DEVICE DRIVER – AMORPHOUS STRUCTURE.............................VIII FIGURE 4 LAYERED DEVICE DRIVER – WELL DEFINED STRUCTURE...............................VIII FIGURE 5 DEVICE DRIVER ARCHITURE ...........................................................................IX FIGURE 6 PSP TOP LEVEL DIRECTORY STRUCTURE .................................................. XVIII FIGURE 7 PAL OS DIRECTORY STRUCTURE ............................................................. XVIII I Chapter 1 Introduction This chapter introduces the DM6437/C6424 DSP/BIOS PSP to the user by providing a brief overview of the purpose and construction of the DM6437/C6424 DSP/BIOS PSP along with hardware and software environment specifics in the context of DM6437/C6424 DSP/BIOS PSP deployment. II 1.1 Overview The DM6437/C6424 PSP is aimed at providing fundamental software abstractions to DM6437/C6424 EVM resources and plugs the same into BIOS operating systems so as to enable and ease application development by providing suitably abstracted interfaces. 1.1.1 Supported Services and features This release of DM6437/C6424 DSP/BIOS PSP provides the following:  PAL OS for BIOS  EDMA3 driver  UART, I2C, McBSP, NAND, McASP  VPFE, VPBE, Previewer, Resizer, H3A and Histogram (Only DM6437)  PAL SYS (VLYNQ and PCI)  Sample applications 1.1.2 System Requirements The following products are required to be installed for using the DM6437/C6424 DSP/BIOS PSP:  CCS 3.3.38  DM6437/C6424 EVM  Code generation tools : 6.0.8  DSP-BIOS 5.31.06 for higher for DM6437  DSP-BIOS 5.31.06 for higher for C6424 1.2 Driver Software Architecture This section gives detail on the overall architecture of TI device driver. 1.2.1 Functional Decomposition The device driver is partitioned into distinct sub-components, consistent with the roles and responsibilities already discussed in section 1.3. In the following sub-sections, each of these III functional sub-components of the device driver is further elaborated. Figure 1 TI Device Driver Functional decomposition LLC/CSLr EVM Hardware Board DDC IOM Static Cfg PAL OS Driver Application Driver Components DSP/BIOS IV The central portion (IOM-DDC-LLC) shown constitutes the mainline device driver component. The surrounding module PAL- OS constitute the supporting system components that facilitates the interfaces between the OS and the above mentioned device driver components. These modules do not specifically deal with device driver but assist the driver by providing OS abstraction. 1.2.2 H/W Device Specific Layer CSL Register Layer: This is comprised of a bunch of symbolic constants (#defines) that expose the register bit-field details of the h/w along with assorted other constants such as bit-field masks, shift values and default settings. LLC Layer: The LLC (low level controller) layer forms the lower most, h/w specific under-pinning of the TI device driver. This is comprised of a set of functions that exposes functions to set various functionalities supported by hardware. Hardware parameters for example in UART baud-rates, stop bits etc. can be set. This parameter setting is done by writing proper values to the respective hardware register. A C-structure data type definition is provided as an as-is map of the peripheral device registers in the processor’s memory map. This structure is termed the Register Overlay structure. The intended mode of usage is to initialize a pointer variable to base address of the peripheral h/w device and typecast it using structure overlay definition. This way, an otherwise un-adorned pointer assumes a strong C-type thereby making it possible to program the h/w registers by read/write to structure member elements. It is important to note here that LLC layer scope is limited to directed access of the underlying h/w device. It does not depend on any specific OS and does not exploit optimizations specific to a given Compiler. In contrast to a device driver, it does not perform operations that are viewed as management of data movement over the peripheral device. It does not model state machines or protocols. Besides, LLC layer is deployed as a per- processor (single CPU) specific library of services. LLC layer philosophy mandates that services exported for one module (read peripheral h/w device) must not call the services of another module. This orthogonal rule is enforced to allow for true componentization of device drivers. 1.2.3 Device Driver Core functionality (DDC) The DDC module for device driver, the OS abstracted portion of the driver which provides basic behavior of the driver, modeling the main functionalities and Protocols. The DDC does not directly touch the underlying h/w, it does so via the LLC layer. Likewise, V it does not make direct reference to any OS services, it glues to the OS via a well specified adaptation module termed the IOM. By mandating certain basic interfaces and extension principles from all implemented device drivers, the DDC helps achieve, uniformity of driver API syntax/semantics across all supported devices and OS platforms. The objective of a good driver partitionning is to sediment as much of the driver behaviour into the DDC as is practical. This calls for a IOM that is thin and efficient. Reuse and performance improvement efforts can then focus on DDC where bulk of the functionality is realized. The DDC is modeled after object oriented style of modular software development. It specifies a base set of interfaces that standardizes the common aspects of all device drivers such as – configuration, creation, initialization & startup, termination and teardown. This base set of function can be extended by introducing operations specific to a particular device – IO Access and IO Control. DDC further encourages formation of device classes while extending the basic functionality. This way, device drivers for h/w components that are similar in data transaction models and control semantics will look alike. The DDC on its own has no existance, it is brought to life by the IOM when the device driver is loaded by the system and removed from the system upon unloading. The IOM has the obligation to pass-on the relevant driver configuration parameters to the DDC during creation phase. The IOM implements a set of functions that adapt the driver to OS. Likewise DDC implements a set of functions that constitute the driver functional interface. To improve componentization of device driver, DDC comprises of C functions which makes use of the LLC Layer for implementation of certain functions that support:  Operations to formally begin/end access to device h/w  Operations to perform onetime setup of the H/W device such as during device driver initialization  Operations to program the H/W device registers to change one or more of its configuration parameters  Operations to query and infer the current state of the H/W device 1.2.4 OS Specific Device Driver Adaptation (IOM) As discussed above, the DDC is not complete unless it is supplemented by the IOM. The IOM “adapts” the driver core to the specific OS. IOM implements aspects such as – threading VI model for transaction processing, Interrupts registration and de- registration, handshaking with OS prescribed upstream/downstream data queues and threads etc., The IOM has full visibility to underlying OS services and is custom-built for a given OS. While the IOM is primarily intended for presenting an OS manifest to the underlying DDC, it is also possible that the IOM upper-edge interface (user level) imbibes the semantics of any pre-specified Framework, if one exists. This is necessary to prevent undue overheads in system integration. 1.2.5 Platform Abstraction Layer for OS services (PALOS) It should be clear by now that a device driver is composed of three main sub-components – the HW specific bottom-edge, the OS specific upper-edge and the central device driver core that makes no reference to any particular OS services. Memory footprint Scalability is a key consideration in deploying such a driver. In this section, we give a quick overview of suggested approach followed in TI device driver implementations. As discussed earlier, both the IOM and DDC publish a table of function pointers for each other to use. However, it must be noticed that, not all the OS specific adaptation services are solicited by DDC in the same context. In addition, it’s not practical to abstract all required OS services due to performance reasons. Therefore, we’d usually end up with a residue part of driver that must be custom built in the IOM by directly availing the OS services. It is this part of the IOM that is exposed through the table of functions to the DDC. The rest of the OS services such as working with Semaphores, Mutexes, Memory buffer pools etc., are generic in nature. If these services are implemented as static functions, rolled into each IOM, memory foot print bloat occurs when there are multiple instances of device drivers in the system. To mitigate memory footprint bloat and difficulties in reuse, all generic OS abstraction services are pulled out as separate compilation units so that only one copy of these need be loaded to resolve all references across different driver instances. This common module is termed the PAL OS and is depicted in figure below as green colored units, located inside the library to the right. VII Figure 2 Genesis of PAL-OS 1.3 Design Philosophy of drivers Central to the philosophy of TI device driver architecture is clarity in separation of roles and responsibilities for the various parts of the device driver. Rather than treat the entire device driver as a monolithic block of code, effort is made to identify the portions of the device driver that are involved in:  Coupling or handshaking with the specific OS  Performing primitive, directed read/write access to the h/w device  Modeling the crux of the driver behavior – protocol, state machine etc this in itself is regardless of any given OS. With this view, the device driver functionality can be enacted by three key roles defined here under:  OS Specific Device Driver Adaptation (IOM)  Device Driver Core, isolated from OS as well as H/W (DDC)  LLC abstraction providing services to perform primitive access necessary to control/configure/examine status, of the underlying h/w device. Since there exists a clear separation of roles and responsibilities of the three sub-components of the driver, the prescribed architecture helps in creation of robust device drivers through tested/reusable pieces. Besides, it ensures in maintaining uniform semantics for similar services, supported across different drivers, for different platforms. VIII The figure below further elucidates the driving philosophy in partitioning the device driver into distinct functional sub- components – IOM, DDC and LLC. Figure 3 Monolithic Device Driver – Amorphous structure Figure 4 Layered Device Driver – Well defined structure IX Figure 5 Device driver Architure 1.3.1 Design Goals The following are the key device driver design goals being factored by proposed TI architecture:  Uniformly styled drivers, promoting increased reuse and code familiarity to developers  Minimal overheads in integrating TI device driver into any Software System 