Project Name: SRGP_bf561.dpj Project Type: ADSP-BF533 [ ] ADSP-BF537 [ ] ADSP-BF561 [X] Hardware Used: ************************************** ************************************** *** PLEASE READ THE RELEASE NOTE *** *** FOR SPECIFIC HARDWARE AND *** *** SOFTWARE CONFIGURATIONS *** *** SUPPORTED BY THIS APPLICATION *** ************************************** ************************************** ADSP-BF561 EZ-Kit Blackfin A-V EZ-Extender Analog Devices VisualDSP++ VisualDSP++ Emulator TV with NTSC AV input System Services Components Used: DMA Manager [X] Deferred Callback Manager [ ] Interrupt Manager [X] Timer Module [ ] Power Management Module [X] Flag Module [ ] External Bus Interface Unit Module [X] Port Module [ ] OVERVIEW ======== This application demonstrates a port of the Simple Raster Graphic Package (SRGP) to the ADSP-BF561 dual core Blackfin DSP. SRGP was developed at Brown University and is available at http://www.cs.brown.edu/software/. An accompanying text book: "Computer Graphics: Principles and Practice" is also helpful in understanding SRGP. RUNNING THE APPLICATION ======================= This application runs on the ADSP-BF561 EZ-KIT Lite with or without the A/V Extender. When an A/V extender is plugged in, the redundant hardware on the A/V extender overrides the same hardware on the EZ-Kit. 1. Hardware settings -------------------- a. Video interface with video encoder in Blackfin A-V Ez-Extender ----------------------------------------------------------------- Connect Blackfin A-V EZ-Extender on top of ADSP-BF561 EZ-KIT Lite -- BF561 Ez-Kit -- SW2: 1-OFF 2-OFF 3-OFF 4-OFF 5-OFF 6-OFF SW3: 1-OFF 2-ON 3-ON 4-OFF SW4: 1-ON 2-ON 3-ON 4-ON 5-OFF 6-OFF SW5: 1-OFF 2-OFF 3-ON 4-OFF SW10: 1-OFF 2-OFF 3-OFF 4-OFF 5-OFF 6-OFF SW11: 1-OFF 2-OFF 3-OFF 4-OFF SW12: 1-ON 2-ON 3-ON 4-ON SW13: 1-ON 2-ON -- Blackfin A-V EZ-Extender -- JP1: No Connection JP2: 1-2 JP3: No Connection JP4: 1-2 JP5: 5-6 JP6: No Connection JP7: No Connection JP8: 3-5 4-6 7-8 JP9: 3-5 b. Video interface with onboard video encoder in ADSP-BF561 EZ-KIT Lite ------------------------------------------------------------------------ -- BF561 Ez-Kit -- SW2: 1-OFF 2-OFF 3-OFF 4-OFF 5-OFF 6-ON SW3: 1-OFF 2-ON 3-ON 4-OFF SW4: 1-ON 2-ON 3-ON 4-ON 5-ON 6-OFF SW5: 1-OFF 2-OFF 3-ON 4-ON SW10: 1-OFF 2-OFF 3-OFF 4-OFF 5-OFF 6-OFF SW11: 1-OFF 2-OFF 3-OFF 4-OFF SW12: 1-ON 2-ON 3-ON 4-ON SW13: 1-ON 2-ON 2. ADSP-BF561 EZ-KIT Lite - Push Button functions ------------------------------------------------- Push Button 1 (SW6): Moves to previous screen Push Button 2 (SW7): Moves to next screen Push Button 3 (SW8): not used Push Button 4 (SW9): not used 3. If using an emulator, make sure that external SDRAM is initialized before downloading the program. Using "Settings"->"Target Options->Use XML reset values" is the most straight-forward way of doing this. This step is not required is using the EZ-KIT's USB debug agent connection. 4. External Connections ----------------------- Connect the middle white video plug on the VIDEO IN/OUT bank to an NSTC capable display/television with composite video input. Set the display to the corresponding video input. RCA-style jacks labeled J6 (ADSP-BF561 Ez-Kit) or J7 (Blackfin A-V Ez-Extender) +---------------------------------------------------+ | O O < Video Out O | (White) | O O O | (Red) +---------------------------------------------------+ J6/J7 NOTE: VisualDSP++ Image Viewer may also be used. Set the parameters for raw pixel data, beginning at address 0, memory stride 1, UYVY format. The dimensions are 858x525. 5. Operational Description --------------------------- - In VisualDSP, open the project srgp_bf561.dpj - Select 'Project->Rebuild Project' to build all the sources and load the program to the target. - Select 'Debug->Multiprocessor Run' to run the program. You will see the welcome screen. - Follow the on-screen instructions, displayed with the graphics on the monitor, using the EZ-KIT's first two push-buttons to move forward and backward through the screens. NOTE: ===== The screen buffer uses the first portion of bank 0 of external memory of the EZ-KIT Lite. The memory after address 0x0 is reserved for this purpose, inside of the LDF. That address may be changed by reserving a different area in the LDF, and changing the variable inside "main()" in the file "srgp.c" where the address of the canvas area is specified. Notes about the Linker Description File (LDF) ============================================= Note that this project uses the first portion of bank 0 of external memory of the EZ-KIT Lite as the screen buffer; the memory after address 0x0 is reserved for this purpose. The LDF used in this application is "srgp-BF561sc.ldf". This "single core" LDF is used for applications that run on core A, with no program to run on core B. After hardware reset, core A begins running, but core B is held in the idle state. The only two ways that Core B can run, is for Core A to clear COREB_SRAM_INIT (bit 5) in the SICA_SYSCR register, or for the VisualDSP emulator to perform it's connection sequence, which releases Core B from the idle state. (For that reason, when using the emulator, a program must ALWAYS be loaded to core B program space, even if it's just an idle loop.) For the System Services Power Management Module to perform its initialization, which involves programming the PLL or affecting the SDRAM settings, both cores must be in an idled state. Dual core programs and single core programs, whether boot loaded, or loaded with the VisualDSP emulator) require a mechanism for Core A to bring Core B into IDLE, while the PLL or EBIU changes are applied. The System Services power management module employs one of the two supplemental interrupts to put core B into the IDLE state, while Core A programs the PLL or EBIU. Core A raises supplemental interrupt 0 on Core B. The Core B supplemental ISR executes an IDLE instruction, while Core A programs the PLL. A "lock variable" (defined in the source file "adi_pwr_lockvar.c") is used for Core A to alert Core B of the completion of the PLL/EBIU programming, so that Core B can resume activity. This mechanism is provided automatically by default, by simply calling the adi_pwr_Init() function on both cores. To turn off this default mechanism, and place the responsibility of the synchronization with the client application, call adi_pwr_init with the command: ADI_PWR_CMD_SET_AUTO_SYNC_DISABLED. When the EBIU module is used in combination with the power management module, Core A uses Core B synchronization while applying SDRAM changes. Unlike the power module, automatic synchronization is disabled by default, but can be enabled by calling the adi_ebiu_init function with the command ADI_EBIU_CMD_SET_AUTO_SYNC_ENABLED. NOTE: Since this mechanism is used to apply changes to SDRAM settings, the Core B Supplemental ISR is cannot be located in SDRAM, but must be located in L1 memory. For this reason, when using dual core power initialization, the System Services library must be located in L1, while the synchronization lock variable ("adi_pwr_lockvar") must be in shared L2 memory, to be accessed by both core. This particular application uses the function 'ezInit(1)', where the 1 represents the number of cores (1 or 2). See the file 'SDK-ezkitutilities.c' to see how ezInit calls ezInitPower which performs the sequence described above. --------------------------------------------- SOFTWARE OWNERSHIP AND INTELLECTUAL PROPERTY --------------------------------------------- ADI_GRAPH was developed by Analog Devices. The algorithms are generally well known, but acknowledgement must be made to "Computer Graphics: Principles and Practice", particularly for its fixed-point ellipse algorithm. Permission is grant to use ADI_GRAPH for any purpose and is provided without warranty. The .BDF fonts are those distributed with X-Windows in its ...\xc\fonts\bdf directory. Copyright information can be found on a per-font basis within the .BDF file's comments. SRGP was developed by Brown University and it owns the copyright. Details concerning its use can be found in the file COPYING_POLICY.TXT. This program was developed by Analog Devices. Permission is granted to use ADI_GRAPH for any purpose and is provided without warranty. ------------------------------------ LIMATIONS, AND NOTEWORTHY BEHAVIORS ------------------------------------ This program demonstrate the functionality available within SRGP and ADI_GRAPH. It also runs on Redhat Linux. To the extent practical, this Blackfin port emulates the look of Linux (X-Windows). This suggests that developing your SRGP code on an X-Windows platforms and then porting it to Blackfin will "mostly work". There is only a single video buffer in this application. As a result, you may see a momentary burst of static when switching pages and/or your display may loose synch briefly. GENERAL Writing a single "pixel" will in fact write to both the even and odd frames of the interlaced display, to prevent screen flicker. This behavior can be changed by modifying the file 'adi_graph_driver.c' and rebuilding the adi_graph library. LINES, PATTERNS AND FILLS Pixmaps interfaces are not supported. SRGP_setWriteMode() is not supported and all writes will behave as WRITE_REPLACE. SRPG_setLineWidth() is not suppored. SRGP_setLineStyle() *is* available, as is SRGP_setFillStyle() (except the PIXMAP_PATTERN style as noted above). SRGP_setFillBitmapPattern() is supported for rectangles only. POLYGONS SRGP_fillPolygon() is not supported. FONTS SRPG's SRGP_loadFont() API is unavailable. Instead, SRGP_ADI_loadFont() is provided. This is because SRGP_loadFont() looks up by name (char*), requiring every font to linked into the program because the fonts actually required cannot be determined at build-time. SRGP_ADI_loadFont() "looks up" by symbol name, allowing the linker to eliminate fonts not specifically referenced by callers. The symbol names for support fonts can be found in the include file 'adi_graph_font_decls.h' located in "BlackfinSDK/Include/adi_graph/fonts". COLORS SRGP_loadCommonColor() is supported, but be aware that its use will link in a rather large data section into your program (~4KB). Loading a new color into an existing entry into color table with SRGP_loadColor() will not cause existing "instances" of the old color to be swapped with the new. Thus, color table "flicker/flash" effects and the link cannot be done using this technique. Conversely, only a very small color table is needed to support an arbitrary number of colors, and new colors can overwrite existing colors without effecting already-rendered pixels. ELLIPSES AND ARC All 360 degree of ellipses are always drawn. All "startangle" and "endangle" parameters are ignored. SRGP_setLineStyle() will have not effect on ellipses. Ellipse will always be drawn as if the line style were CONTINUOUS. KEYBOARD, POINTER, AND BEEP None of these interfaces are supported. SOFTWARE HIERARCHY ================== This application consists of the following files: "../srgp.c" - Core A source file "../../../BFinUtils/ADSP-BF561/SDK-CoreB_Idle.doj" - Core B object file, pre-built and linked to the start of core B L1 program space, executes an idle loop forever, enabling core A to write the PLL and EBIU settings. "../../../BFinUtils/SDK-ezkitutilities.c" - EZ-Kit utilities source file for Blackfin processors "../../../BFinUtils/SDK-video.c" - EZ-Kit Video utilities source file for Blackfin processors "../../../Include/SDK-ezkitutilities.h" - EZ-Kit utilities include file for Blackfin processors "../../../Include/SDK-video.h" - EZ-Kit Video utilities include file for Blackfin processors "./SRGP_bf561.dpj - project file that builds this application - defaults to debug "./srgp-BF561sc.ldf" - linker description file for an ADSP-BF561 single core application using system services applications, reserves part of SDRAM0 for the canvas, and automatically links "SDK-CoreB_Idle.doj" to Core B's L1 memory space, so that core B remains in IDLE throughout the life of the program. "../../../Lib/adi_graph561d.dlb" - adi graph library (described below) debug version "../../../Lib/adi_graph_fonts.dlb" - fonts library (needed when using text) "../../../Lib/libsrgp561d.dlb" - SRGP library (described below) debug version Within this SRGP program, there are two more layers of software which comprise the SRGP and ADI_GRAPH libraries. SRGP Library ============ Analog Devices ported the Simple Raster Graphic Package (SRGP) to the ADSP-BF561 dual core Blackfin DSP, and demonstrates it's use in this application. This application, and others that use the SRGP library, will link to the saved SRGP library, located in the "BlackfinSDK/Lib" folder. The source directory structure for the ADSP-BF561 SRGP library is found in the folder: "BlackfinSDK/Algorithms/SRGP/ADSP-BF561". The code has been modified, in some cases extensively, to use the 'adi_graph' library. These are key subdirectories for the 'SRGP' library: "../../../Algorithms/SRGP/include" - include files, specific to the SRGP library build. "../../../Include/SRGP" - global include fles. Any project using SRGP should add this path to the compiler search path (-I directories). "../../../Lib" - libsrgp.dlb or libsrgpd.dlb. The SRGP library. The "d" suffix indicates that this version was built using the VisualDSP++ 4.5 "Debug" configuration (no optimizations, include debugging information). One of these libraries (debug or release version) must be linked with the project, to produce the final executable(s) for the application. "../../../Algorithms/SRGP/src" - The include files specific to the SRGP library, only. ADI_GRAPH library ================= This application also uses the 'adi_graph' library. The saved 'adi_graph' library, that is linked into this application, is located in the "BlackfinSDK/Lib" folder. The project file that rebuilds the 'adi_graph' library is found in the folder: "BlackfinSDK/Algorithms/adi_graph/ADSP-BF561". The 'adi_graph' library is used for drawing graphic primitives such as lines and ellipses. This library is useful either SRGP, or independent of SRGP. While SRGP requires 'adi_graph', the reverse is not true, 'adi_graph' may be used without SRGP. SRGP can be considered a "shell" or "wrapper" around 'adi_graph'. SRGP itself has no primitive operations. The primitives are all defined in 'adi_graph.dlb'. These are key subdirectories for the 'adi_graph' library: "../../../Include/adi_graph" - global adi_graph include files. Any project that uses ADI_GRAPH or uses SRGP should add this path to the compiler (-I directories). "../../../Algorithms/adi_graph/fonts" - Bitmap fonts in .BDF format. The font library 'adi_graph_fonts.dlb' can only be built by running the 'port_all.tcl' script in this directory. This script generates C source code for every .BDF file, compiles each C file, and then uses ELFAR to create the .dlb file. "../../../Lib" - 'adi_graph.dlb', 'di_graphd.dlb', and 'adi_graph_fonts.dlb'. The versions with the "d" suffix were built with VisualDSP in "Debug" configuration (no optimizations, includes debugging information). One of these libraries must be linked to the SRGP program. NOTE: The fonts library, 'adi_graph_fonts.dlb', is only required if your project displays text. "../../../Algorithms/adi_graph/src" - Source code for the 'adi_graph' library.