Home

ANALOG DEVICES VisualDSP 4.5 Device Drivers System Services Manual for Blackfin Processors (Revision 2.1 April 2006)

1.
2. Enumeration Type Description ADI PORTS DIR GP PF4 Enable PF4 pin for GPIO use ADI_PORTS_DIR_GPIO_PF5 Enable PF5 pin for GPIO use ADI_PORTS_DIR_GPIO_PF6 Enable PF6 pin for GPIO use ADI PORTS DIR GPIO PF7 Enable PF7 pin for GPIO use ADI PORTS DIR GPIO PF8 Enable PF8 pin for GPIO use ADI PORTS DIR GPIO PF9 Enable PF9 pin for GPIO use ADI PORTS DIR GPIO PF10 Enable PF10 pin for GPIO use ADI PORTS DIR GPIO PF11 Enable PF11 pin for GPIO use ADI PORTS DIR GPIO PF12 Enable PF12 pin for GPIO use ADI PORTS DIR GPIO PF13 Enable PF13 pin for GPIO use ADI PORTS DIR GPIO PF14 Enable PF14 pin for GPIO use ADI PORTS DIR GPIO PF15 Enable PF15 pin for GPIO use ADI PORTS DIR GPIO PGO Enable PGO pin for GPIO use ADI PORTS DIR GPIO PG Enable PG1 pin for GPIO use ADI PORTS DIR GPIO PG2 Enable PG2 pin for GPIO use ADI PORTS DIR GPIO PG3 Enable PG3 pin for GPIO use ADI PORTS DIR GPIO PG4 Enable PG4 pin for GPIO use ADI PORTS DIR GPIO PG5 Enable PG5 pin for GPIO use ADI PORTS DIR GPIO PG6 Enable PG6 pin for GPIO use ADI PORTS DIR GPIO PG7 Enable PG7 pin for GPIO use ADI PORTS DIR GP PG8 Enable PG8 pin for GPIO use ADI PORTS DIR GPIO PG9 Enable PG9 pin for GPIO use ADI PORTS DIR GPIO PGI10 Enable PG10 pin for GPIO use ADI PORTS DIR GPIO PG11 Enable PG11 pin for GPIO
3. Table 6 3 DMA Commands Contd DMA Manager Command ID Value Description ADI DMA CMD TC SET MDMA ul6 Sets the traffic control MDMA value ADI DMA CMD TC GET DCB COU ul6 Gets the traffic control TER DCB counter value ADI DMA CMD TC GET DEB COU ul6 Gets the traffic control TER DEB counter value ADI DMA CMD TC GET DAB COU u16 Gets the traffic control TER DAB counter value AD A CMD TC GET MDMA CO ul6 Gets the traffic control UNTER MDMA counter value VisualDSP 4 5 Device Drivers and System 6 65 Services Manual for Blackfin Processors Public Data Structures Enumerations and Macros 6 66 VisualDSP 4 5 Device Drivers and System Services Manual for Blackfin Processors 7 PROGRAMMABLE FLAG SERVICE This chapter describes the programmable flag service The programmable flag service within the System Services Library pro vides the application with an easy to use interface into the programmable flag sometimes called General Purpose I O GPIO subsystem of the Blackfin processor This chapter contains the following sections e Introduction on page 7 2 e Operation on page 7 3 Flag Service API Reference on page 7 14 Public Data Types Enumerations and Macros on page 7 31 VisualDSP 4 5 Device Drivers and System 7 1 Services Manual for Blackfin Processors Int
4. ADI PWR RESULT INVALID SSEL An invalid value for SSEL has been specified ADI PHR INVALID CSEL SSEL The core clock divider is greater that the System COMBINATION clock divider value or both ADI PUR CSEL NONE and ADI PWR SSEL NONE are specified VisualDSP 4 5 Device Drivers and System 3 19 Services Manual for Blackfin Processors Power Management API Reference adi pwr Control Description This function enables the dynamic power management registers to be con figured or queried according to command value pairs ADI PWR COMMAND PAIR on page 3 49 specified in one of three ways 1 A single command value pair is passed adi pwr Control ADI PWR CMD SET INPUT DELAY void ADI PUR INPUT DELAY ENABLE 13 2 A single command value pair structure is passed ADI PWR COMMAND PAIR cmd ADI PUR CMD SET INPUT DELAY void ADI PWR INPUT DELAY ENABLE hi adi pwr Control ADI PWR CMD PAIR Cvoid amp cmd 3 A table of ADI PWR COMMAND PAIR structures is passed The last entry in the table must be ADI PWR CMD END ADI PHR COMMAND PAIR table ADI PWR CMD SET INPUT DELAY void ADI PWR INPUT DELAY ENABLE ADI PWR CMD SET OUTPUT DELAY void ADI PWR OUTPUT DELAY ENABLE ADI PUR CMD END 0j hs adi_pwr_Control ADI_PWR_CMD_TABLE 3 20 VisualDSP 4 5 Device Drivers and System Services Manual for Blackfin Pro
5. adi_dma_SetMapping Sets the DMA Channel ID to which a peripheral is mapped See adi_dma_SetMapping on page 6 54 Memory DMA Functions adi dma MemoryOpen Opens a memory DMA stream for use See adi dma MemoryOpen on page 6 48 adi dma MemoryClose Closes a memory DMA stream See adi_dma_MemoryClose on page 6 43 adi dma MemoryCopy Copies memory in a linear one dimensional fashion See adi dma MemoryCopy on page 6 44 adi dma MemoryCopy2D Copies memory in a two dimensional fashion See adi dma MemoryCopy2D on page 6 46 6 34 VisualDSP 4 5 Device Drivers and System Services Manual for Blackfin Processors adi dma Buffer Description DMA Manager This function assigns a one shot or a circular buffer to a DMA channel and configures the DMA Channel according to the parameters supplied Prototype ADI DMA RESULT adi dma Buffer ADI DMA CHANNEL HANDLE void ADI DMA CONFIG REG ul6 S16 ul6 S16 ChannelHandle Star Config XCount XModi YCount YModif tAddress fy Lis VisualDSP 4 5 Device Drivers and System Services Manual for Blackfin Processors 6 35 DMA manager API Reference Arguments ChannelHandle This argument uniquely identifies the DMA channel that the buffer is to be assigned to and is the value returned when the DMA channel was opened StartAddress This is the location of the start
6. adi dev Read Provides a device with buffers for inbound data VisualDSP 4 5 Device Drivers and System 1 21 Services Manual for Blackfin Processors Device Driver Overview e adi dev Write Provides a device with buffers for outbound data adi dev Control Sets detects control and status parameters for a device Like the System Service APIs the Device Driver API is designed to be called using the standard calling interface of the development toolset s C run time model The Device Driver API can be called by any C or assem bly language program that adheres to the calling conventions and register usage of the C run time model Device Driver Arc hitecture The Device Driver model separates the functionality of device drivers into two main components the Device Manager and the physical drivers The Device Manager is a software component that provides much of the functionality common to the vast majority of device drivers For example depending on how the application wants the device driver to operate the application may command a device driver to operate in synchronous mode or asynchronous mode In synchronous mode when the application calls the adi dev Read or adi dev Write API function to read data from or send data to the device the API function does not return to the application until the oper ation has completed In asynchronous mode the API function returns immediately to the application while
7. ADI DCB RESULT SUCCESS The queue server was successfully initialized ADI DCB RESULT NO MEMORY Insufficient memory for one queue entry was encoun tered ADI DCB RESULT QUEUE IN USE A queue server has already been opened for use by the specified IVG 5 20 VisualDSP 4 5 Device Drivers and System Services Manual for Blackfin Processors Deferred Callback Manager adi dcb Post Description This function posts a callback function and associated argument values to the queue server identified by the handle argument for further processing A callback is associated with a priority level so that higher priority call backs run before lower priority ones To run all callbacks at the same priority level assign the same priority to each callback posted Prototype ADI DCB RESULT adi dcb Post ADI DCB HANDLE hServer ul6 Priority ADI DCB CALLBACK FN Callback void pHandle u32 u32A rg void pArg VisualDSP 4 5 Device Drivers and System 5 21 Services Manual for Blackfin Processors DCB Manager API Reference Arguments Table 5 1 Adi_dcb_Post Arguments Argument Explanation hServer This is the handle of the required queue server Priority This is the priority level at which the callback is to run the lower the number the higher the priority There is no real limit on the value supplied Callback This is the address of the
8. See ADI_EBIU_SDRAM_BANK_ SIZE on page 4 30 and ADI EBIU SDRAM BANK COL WIDTH on page 4 30 for details of the size and width fields The bank field is intended for future use and has no meaning for the ADSP BF531 ADSP BF532 ADSP BF533 and ADSP BF534 ADSP BF536 ADSP BF537 Blackfin processors 4 22 VisualDSP 4 5 Device Drivers and System Services Manual for Blackfin Processors Extemal Bus Interface Unit Module ADI EBIU TIME The ADI EBIU TIME structure enables users to specify a timing value as an integral number of a given unit It is defined as typedef struct ADI EBIU TIME u32 value ADI EBIU TIMING UNIT units ADI EBIU TIME Where ADI EBIU TIMING UNIT is an enumeration type defined in the fol lowing table ADI EBIU T G UNIT MILLISEC The time value specified by the associated value in the ADI EBIU TIME structure is in milliseconds ms ADI EBIU T G UNIT MICROSEC The time value specified by the associated value in the ADI EBIU TIME structure is in microseconds ms ADI EBIU T G UNIT NANOSEC The time value specified by the associated value in the ADI EBIU TIME structure is in nanoseconds ns ADI EBIU T G UNIT PICOSEC The time value specified by the associated value in the ADI EBIU TIME structure is in picoseconds ps ADI EBIU T G UNIT FEMTOSEC gt he time v
9. callback yey Where event typically defines some event for example DMA completion and data typically points to an appropriate location in memory meaning ful within the context of the callback function Within the DMA manager context this argument is either the address of an appropriate descriptor or data buffer 5 6 VisualDSP 4 5 Device Drivers and System Services Manual for Blackfin Processors Deferred Callback Manager If for any reason users want to flush the queue of entries for the above callback this can be achieved in one of two ways Either users can call the adi dcb Remove function directly or call it indirectly using the adi dcb Control function See adi dcb Terminate for further details and an example of its use along with any other requests The following code describes the direct approach adi dcb Remove p DCB handle handle to required queue server ClientCallback Address of callback function to flush Finally if required the queue can be closed and the DCB manager terminated adi dcb Close p DCB handle handle to required queue server adi dcb Terminate VisualDSP 4 5 Device Drivers and System 5 7 Services Manual for Blackfin Processors Interoperability With an RTOS Interoperability With an RTOS The DCB manager employs two functions adi dcb RegisterISR and adi dcb Forward to interface with the different RTOS environments including standalone mode
10. 9 PORTCONTROL SERVICE This chapter describes the port control manager service This service is available for ADSP BF534 ADSP BF536 and ADSP BF537 class of processors only This chapter contains the following sections Introduction on page 9 2 Using the Port Control Manager on page 9 2 Port Control Manager API Reference on page 9 4 Public Data Types Enumerations and Macros on page 9 17 VisualDSP 4 5 Device Drivers and System Services Manual for Blackfin Processors 9 1 Introduction Introduction The port control manager service within the System Services Library pro vides the client applications developer with a means of assigning the programmable flag pins to various functions For instance the flag pins required for SPORTO usage can be set up with a single call to the adi ports EnableSPORT function Where necessary the memory mapped registers for the appropriate peripherals are queried to determine behavior For example the port con trol manager can determine whether two internal frame syncs are required by interrogating the PPI CONTROL register However it is the responsibility of the client program to configure the PPI control registers prior to enabling the required flag pins This is the usual practice within the Device Driver Model where port control and the setting of flag values are done at the point of enabling dataflow The port control manager is applicable only to processors that
11. ADI FLAG RESULT Each API function of the Flag Service returns an ADI FLAG RESULT enu meration as a return code As with all system services generic success is defined as 0 while generic failure is defined as 1 This allows the calling function to quickly evaluate the return code for a zero or non zero value All detailed result codes for the Flag Service begin with the value ADI FLAG ENUMERATION START for easy identification Result code Description ADI FLAG RESULT SUCCESS Function executed correctly ADI FLAG RESULT FAILED Function execution not completed ADI FLAG RESULT BAD FLAG ID Invalid flag ID ADI FLAG RESULT INTERRUPT MANAGER A call to the interrupt manager failed for some rea ERROR son ADI FLAG ERROR REMOVING CALLBACK An error occurred removing a flag callback func tion ADI FLAG RESULT ALL IN USE All callback memory supplied at initialization is in use ADI FLAG RESULT BAD GROUP The port control service returned an error 7 32 VisualDSP 4 5 Device Drivers and System Services Manual for Blackfin Processors ADI FLAG EVENT Programmable Hag Service The ADI FLAG EVENT enumeration defines the type of callback event that occurred The table below enumerates all possible event codes from the Flag Service This enumeration type is different from all other event types for system services As such a single callback function can be used for
12. Blackfin lib src services This directory contains all the source code files and non API include files for the System Services Also in this directory are the VisualDSP project files that can be used to rebuild the libraries Blackfin include services This directory contains all API include files for the System Services VisualDSP users can simply rebuild the System Services Library by using the build command after opening the appropriate VisualDSP project file To rebuild the libraries using other development toolsets the following process should be performed 1 Set the pre processor include path to include Blackfin include services and blackfin lib src services VisualDSP 4 5 Device Drivers and System 1 15 Services Manual for Blackfin Processors System Services Overview 2 Define the processor variant according to the definitions in the file services h 3 Define the silicon revision macro SILICON REVISION to the proper value Refer to the description of the si revision switch 3 in the compiler manual for more information 4 Compile assemble all files in the Blackfin lib src services directory 5 Link the appropriate compiled assembled objects into a library Include all object files without any operating environment exten sion such as VDK and all object files with the appropriate operating environment extension specific for the environment being targeted such as VDK Exam
13. ChannelHandle This argument uniquely identifies the DMA channel to be closed and is the value returned when the DMA channel was opened WaitFlag If set to TRUE 1 the argument instructs the DMA Manager to wait for ongoing transfers to complete before closing the channel otherwise if set to FALSE 0 the chan nel will be closed immediately terminating any ongoing transfers Return Value ADI DMA RESULT SUCCESS DMA Channel successfully closed ADI DMA RESULT BAD HANDLE ChannelHandle does not point to a valid channel ADI DMA RESULT CANT UNHOOK _INTERRUPT The data handler and or error handler cannot be unhooked VisualDSP 4 5 Device Drivers and System 6 37 Services Manual for Blackfin Processors DMA manager API Reference adi dma Control Description The adi dma Contro function controls queries the operation of the spec ified DMA Channel The function can be used in several ways A single command is passed adi dma Control ChannelHandle ADI DMA CMD SET LOOPBACK void TRUE A single command value pair is passed for example ADI DMA CMD VALUE PAIR cmd ADI DMA CMD SET WORD SIZE void ADI DMA WDSIZE 32BIT adi dma Control ChannelHandle cmd CommandID cmd Value A single ADI DMA CMD VALUE PAIR structure is passed by reference adi dma Control ChannelHan dle ADI DMA CMD VALUE PAIR amp
14. Command Description ADI PUR CMD SET CCLK TABLE The address of a table containing ADI PWR NUM VLEVS values of type u16 detailing the maximum CCLK fre quency for each ADI PWR VLEV value These values will be used instead of the data sheet values ADI PUR CMD SET EZKIT An ADI_PWR_EZKIT value to identify the EZ KIT for which the power management is to be configured This command establishes all the required values as detailed above see ADI PWR EZKIT on page 3 52 ADI PUR CMD SET PROC VARIANT An ADI PWR PROC KIND value specifies the processor variant mandatory see DI PWR PROC KIND on page 3 58 ADI PWR CMD SET PACKAGE An ADI PUR PACKAGE KIND value describes the packaging type of the processor mandatory See ADI PWR PROC KIND on page 3 58 ADI PR CMD SET CLKIN A u16 value specifies the external clock frequency CLKIN supplied to the processor Mandatory ADI PWR CMD SET VDDINT An ADI PWR VLEV value specifies the Core Voltage Level This should only be passed to adi pwr Init if an external voltage regulator is to be used as its presence instructs the module to bypass the internal reg ulator see ADI PWR VLEV on page 3 63 ADI PUR CMD SET VDDEXT An ADI PWR VDDEXT value specifies the external voltage level applied to the internal voltage regulator mandatory See ADI PWR VDDEXT on page 3 62 VisualDSP 4 5 D
15. Timer Service API Reference adi tmr CoreControl Description The adi tmr CoreControl function inverts the current value of the flag If the flag is a logical 1 driving high this function makes the flag a logical 0 driving low If the flag is a logical 0 driving low this function makes the flag a logical 1 driving high Prototype void adi tmr CoreControl ADI TMR GP CMD void ve Arguments Command Value Command Identifier specifying the timer parameter that is being addressed See ADI TMR CORE CMD on page 8 33 for a list of all core timer command identifiers Value A command specific value that is typically the value of the parameter being set or a location into which a value read from the timer is stored Return Value ADI_TMR_RESULT_SUCCESS The function completed successfully Any other value An error has occurred See ADI_TMR_RESULT on page 8 32 for a list of return codes 8 22 VisualDSP 4 5 Device Drivers and System Services Manual for Blackfin Processors Timer Service adi tmr WatchdogControl Description The adi tmr WatchdogControl function configures and controls the set tings of the watchdog timer Prototype void tmr WatchdogControl ADI TMR GP CMD Command void Value 3 Arguments Command Identifier specifying the timer parameter that is being addressed See ADI TMR WDOG CMD on page 8 34 for a list
16. VisualDSP 4 5 Device Drivers and System 1 19 Services Manual for Blackfin Processors Device Driver Overview management module must be initialized prior to the opening of any device driver There are basically three approaches that can be adopted Define a function to initialize the System Services and Device Manager and call it from a user modifiable section of the start routine in Project basiccrt s e Assign the initialization to the highest priority boot thread or e Usea separate boot thread to perform the initialization and set it at the highest priority and let it either yield to other threads once completed or be destroyed Please take care to use global and not thread memory to initialize the System Services and Device Man ager in this way Device Driver Overview Device drivers provide a mechanism for applications to control a device effectively Devices may be on chip or off chip hardware devices or even software modules that are best managed as virtual devices Device drivers are typically constructed such that the application is insulated from the nuances of the hardware or software being controlled In this way both the device drivers and the devices that are being controlled can be updated or replaced without affecting the application The Analog Devices Device Driver model has been created to provide a simple convenient method for applications to control devices commonly found in and around Analog D
17. When the outermost adi_int_ExitCriticalRegion function is called the saved IMASK value with the new bit settings is restored If upon entering this function the processor is not within a protected region of code the live IMASK register is updated accordingly Information on the implementation details for this function in other oper ating environments can be found in the file adi_int_xxx h located in the Blackfin include services directory where xxx is the operating environment Note that regardless of the implementation details the API is consistent from environment to operating environment Changes to application soft ware are not required when code is moved to a different operating environment Prototype void adi_int_ClearIMASKBits ADI_INT_IMASK BitsToClear 2 24 VisualDSP 4 5 Device Drivers and System Services Manual for Blackfin Processors Interrupt Manager Arguments BitsToClear Replica of the IMASK register containing bits that are to be cleared in the real IMASK register A bit with a value of T clears the corresponding bit in the IMASK register A bit with the value of 0 leaves the corresponding bit in the IMASK register unchanged Return Value None VisualDSP 4 5 Device Drivers and System 2 25 Services Manual for Blackfin Processors Interrupt Manager API Reference adi int EnterC riticalRegion Description This function creates a condition that protects a
18. _dev_Read Reads data from a device or queues reception buff to a device _dev_Write Writes data to a device or queues transmission buffers to a device adi pdd Close Closes the device In addition to the API functions into the Device Manager the application provides the Device Manager with a callback function Often the Device Manager or physical driver encounters an event that needs to be passed to the user application The event may be an expected event such as an indi VisualDSP 4 5 Device Drivers and System 10 7 Services Manual for Blackfin Processors Using the Device Manager cation that the device driver has completed processing a buffer or it may be an unexpected event such as an error condition that has been generated by the device All events are reported back to the application via a callback function A callback function is simply a function within the user applica tion that the Device Manager calls to pass along event information Theory of Operation The device driver model is built around the concept that a device is used to move data into and or out of the system In most systems a device is used to move data into the system where the data will be processed in some fashion and then another device will take the processed data and move it out of the system Often there are multiple devices running simultaneously in the system The Device Manager provides a simple and straightforwa
19. see ADI_PWR_EZKIT on page 3 52 ADI PUR CMD SET PROC VARIANT An ADI PWR PROC KIND value specifying the processor variant see ADI_PWR_PROC_KIND on page 3 58 ADI PUR CMD SET PACKAGE An ADI PWR PACKAGE KIND value describing the packaging type of the processor see 5 NDI PWR PACKAGE KIND on page 3 56 ADI PUR CMD SET CLKIN A u16 value specifying the external clock fre quency CLKIN in MHz supplied to the proces sor ADI PUR CMD SET VDDINT An ADI PWR VLEV value specifying the Core Voltage Level provided by an external voltage reg ulator see ADI_PWR_VLEV on page 3 63 ADI PUR CMD SET VDDEXT An ADI PWR VDDEXT value specifying the exter nal voltage level applied to the internal voltage regulator see ADI_PWR_VDDEXT on page 3 62 VisualDSP 4 5 Device Drivers and System Services Manual for Blackfin Processors 3 45 Public Data Types and Enumerations Table 3 6 ADI PWR COMMAND Available Commands Contd Command Associated Data Value ADI PUR CMD FORCE DATASHEET VALUES Enforces the Core Clock frequency limits for each voltage level as defined in the relevant data sheet default ADI PUR CMD SET CCLK TABLE The address of a table containing ADI PWR NUM VLEVS values of type u16 detail ing the max CCLK frequency for each ADI PWR VLEV value These values will be used instead of the data s
20. set min TRAS to 44ns ADI EBIU TIME trasmin 44 ADI EBIU TIMING UNIT NANOSECI set min TRP to 20ns ADI EBIU TIME trpmin 20 ADI EBIU TIMING UNIT NANOSEC set min TRCD to 20ns ADI EBIU TIME trcdmin 20 ADI EBIU TIMING UNIT NANOSECI set up command table ADI EBIU COMMAND PAIR ezkit sdram ADI EBIU CMD SET SDRAM BANK SIZE void amp bank size 4 4 VisualDSP 4 5 Device Drivers and System Services Manual for Blackfin Processors Extemal Bus Interface Unit Module ADI EBIU CMD SET SDRAM BANK COL WIDTH void amp bank width ADI EBIU CMD SET SDRAM CL THRESHOLD void 100 MHz ADI EBIU CMD SET SDRAM TRASMIN void amp trasmin ADI EBIU CMD SET SDRAM TRPMIN void amp trpminj ADI EBIU CMD SET SDRAM TRCDMIN void amp trcdmin ADI EBIU CMD SET SDRAM TWRMIN void amp twrmin ADI EBIU CMD SET SDRAM REFRESH void amp refresh ADI EBIU CMD END 0 ki The sample code shows that the minimum TWR value comprises two parts This reflects the definition found in the appropriate Blackfin processor data sheet where the value is expressed as one cycle of SCLK plus 7 5 ns Similarly the SDRAM refresh period value is expressed as the time taken for the given number of refresh cycles The sample code shows this value as 64ms for 8192 cycles For boards that us
21. IM SUN DSP 4 5 Device Drivers and System Services Manual for Blackfin Processors Analog Devices Inc Revision 2 1 August 2006 Part Number 82 000430 01 I3 ANALOG DEVICES Copyright Information 2006 Analog Devices Inc ALL RIGHTS RESERVED This document may not be reproduced in any form without prior express written consent from Analog Devices Inc Printed in the USA Disclaimer Analog Devices Inc reserves the right to change this product without prior notice Information furnished by Analog Devices is believed to be accurate and reliable However no responsibility is assumed by Analog Devices for its use nor for any infringement of patents or other rights of third parties which may result from its use No license is granted by impli cation or otherwise under the patent rights of Analog Devices Inc Trademark and Service Mark Notice The Analog Devices logo Blackfin the Blackfin logo EZ KIT Lite SHARC TigerSHARC and VisualDSP are registered trademarks of Analog Devices Inc All other brand and product names are trademarks or service marks of their respective owners CONTENTS PREFACE Purpose ot This Manwal 2iuuspessece qu b ipiade bp ur akena XXV Intended Audience ouais didt E epit RM d eens XXV Mannal Contente OE ugcieituneshtuinpuebetdaxezia iR eet tua xxvi Technicalor Customer Suppott 2usnsanesqs dao d dbi dades a aep als xxvii Supported Processors quaes duniteivisen o
22. Return Value Description of function return values VisualDSP 4 5 Device Drivers and System 3 17 Services Manual for Blackfin Processors Power Management API Reference adi pwr AdjustFreq Description This function allows the core and system clocks to be modified by specify ing the core and system clock divider ratios CSEL and SSEL in the PLL_DIV register The processor is not idled Prototype ADI PWR RESULT adi pwr AdjustFreq const ADI PWR CSEL csel const ADI PWR SSEL ssel Arguments csel An ADI PWR CSEL value specifies how the Voltage Core Oscillator VCO frequency is to be divided to obtain a new Core Clock frequency see ADI_PWR_CSEL on page 3 50 The divider value cannot exceed the ssel value ssel An ADI_PWR_SSEL value specifies how the VCO frequency is to be divided to obtain a new System Clock frequency see ADI_PWR_CSEL on page 3 50 Return Value In the debug variant of the library the function adi_pwr_AdjustSpeed returns one of the following result codes Otherwise the function returns ADI_PWR_RESULT_SUCCESS ADI_PWR_RESULT_SUCCESS This process completed successfully ADI_PWR_RESULT_CALL_IGNORED The PM module has not been initialized ADI_PWR_RESULT_INVALID_CSEL An invalid value for CSEL has been specified 3 18 VisualDSP 4 5 Device Drivers and System Services Manual for Blackfin Processors Power Management Module
23. Timer service Programmable flag service DMA manager service Deferred callback service Port control ADSP BF534 536 537 processors only Power management service Fxternal bus interface unit Interrupt control service System Services Directory and File Structure All files for the System Services are contained within the blackfin direc tory tree In VisualDSP installations this is the same directory as the one used for core development tools Other development toolsets may use other directory names for their toolkits but the System Services can always be found within the blackfin directory tree To use the System Services applications need only include a single include file in their source code and link with a single System Services Library module that is appropriate for their configuration Accessing the System Services API Applications using the System Services should include the Blackfin include services directory in the compiler and or assembler pre processor search path User source files accessing any of the System VisualDSP 4 5 Device Drivers and System 1 11 Services Manual for Blackfin Processors System Services Overview Services APIs should simply include the services h file located in the Blackfin include services directory User files do not need to include any other files to use the System Services API The System Services API and functionality are uniform and consistent across all Blackfin processo
24. function In addition to the command ID the Value parameter a void type is also passed to the function The mean VisualDSP 4 5 Device Drivers and System 8 33 Services Manual for Blackfin Processors Public Data Types Enumerations and Macros ing of the Value parameter is dependent upon the command ID being passed The table also describes the Value parameter for each command ID Table 8 1 Commands Executed for Core Timer Command ID Value Description ADI_TMR_CORE_CMD_TABLE ADI_TMR_CORE_CMD_ Start of command table VALUE_PAIR ADI_TMR_CORE_CMD_END Ignored End of command table ADI_TMR_CORE_CMD_PAIR ADI_TMR_CORE_CMD_ Command pair VALUE_PAIR D SET ACTIVE TRUE active mode ODE FALSE low power Sets active or low power mode of timer TRUE enabled FALSE disabled ENABLE_TIMER Enables or disables the timer ADI_TMR_CORE SET_AUTO_REL TRUE auto reload Enables or disables automatic OAD FALSE no reload reloading of timer ADI_TMR_COR HAS_INTERRUP u32 Indicates if the timer interrupt T_OCCURRED TRUE enabled has occurred FALSE disabled R_COR RESET_INTERR Ignored Clears the indication that the UPT_OCCURRED timer interrupt has occurred ADI_TMR_COR SET_COUNT u32 Sets the count value for the timer ADI_TMR_COR SET_PERIOD u32 Sets the period
25. in the address of the descriptor union ADI DMA DESCRIPTOR UNION or alternatively the address of the descriptor itself ADI DMA DESCRIPTOR LARGE to the ADI DMA DESCRIPTOR HANDLE data type This descriptor can be either a single descriptor or the first descrip tor in a chain of descriptors Large model descriptors contain all the information necessary for the DMA manager to control the operation of the DMA controller This information includes A pointer to the next large descriptor in the chain If this field is NULL then the given descriptor is the only descriptor the client is submitting to the channel The starting address of the buffer This value is the address in memory where data will initially be read from if the transfer is for outbound data or the address in memory where data will initially be stored if the transfer is for inbound data The configuration word for the transfer This is a 16 bit value that represents the DMA Configuration register for the channel The DMA manager include file provides macros that allow the client to quickly and easily create a configuration word The only fields within the configuration word the client need provide values for are WNR ADI DMA WNR READ Transfer is for outbound data Transfer Direction ADI_DMA_WNR_WRITE Transfer is for inbound data WDSIZE ADI_DMA_WD_SIZE_8BIT Elements are 1 byte wide 8 bits Transfer Element Size c ADI DMA WD SIZE
26. 10 51 custom defined error codes 10 53 defined 10 5 design overview 10 49 entry point 10 37 10 54 extensions 10 52 handles 10 55 shutdown procedure 1 25 source code 10 54 PLL controller resetting 3 33 reset to hardware reset values 3 35 PLL Control register DF bit 3 54 input delay bit 3 56 output delay bit 3 57 PLL DIV register adi pwr AdjustFreq function 3 19 adi pwr SetFreq function 3 37 setting core clock divider bit field 3 53 setting system clock divider bit field 3 64 PLL input divider 3 37 PLL LOCKCNT register 3 47 PLL STAT register 3 47 port control manager assigning programmable flag pins to functions 9 2 defined 9 2 enumeration types 9 17 initializing 9 6 return codes 9 17 terminating 9 7 port control registers 7 3 VisualDSP 4 5 Device Drivers and System Services Manual for Blackfin Processors power management module API functions 3 18 defined 3 1 enabling 4 2 enumerations 3 46 initialization values 3 27 initializing 3 27 macros 3 74 public data types 3 46 return codes 3 62 power mode current 3 25 defining 3 58 power modes active 3 40 deep sleep 3 40 full on 3 40 hibernate 3 40 processor 3 40 sleep 3 40 power saving value for the current PLL and voltage regulator settings 3 26 PPDCallback function 10 53 PPI channel enabling 9 8 PPIEntryPoint variable 10 54 precharge all command 4 35 precharge command 4 13 PrepareBufferList static function
27. 168IT Elements are 2 bytes wide 16 bits ADI DMA WD SIZE 328IT Elements are 4 bytes wide 32 bits DMA2D ADI DMA DMA2D LINEAR One dimensional linear transfer Dimension Select ADI DMA DMA2D 2D Two dimensional transfer VisualDSP 4 5 Device Drivers and System 6 19 Services Manual for Blackfin Processors Theory of Operation DI EN Data Interrupt Enable ADI DMA DI EN DISABLE No callback will be generated ADI DMA DI EN ENABLE The DMA manager generates a callback to the client when the transfer completes The XCount value For one dimensional transfers this value defines the number of elements to be transferred For two dimensional transfers this value defines the inner loop count number of columns The XModi fy value For one dimensional transfers this value defines the address increment decrement stride for each succes sive element For two dimensional transfers this value defines the inner loop address increment decrement stride for each successive element up to but not including the last element in each inner loop After the last element in each inner loop the YModi fy value is applied instead except on the very last element of the transfer The YCount value This parameter is ignored for one dimensional transfers For two dimensional transfers the value represents the outer loop count number of rows The YModi fy value
28. 6 10 6 30 DMACallback function 10 45 10 46 I 10 VisualDSP 4 5 Device Drivers and System Services Manual for Blackfin Processors DMA channel closing 6 22 6 37 configuration 6 22 controlling 6 4 6 38 identifying 6 41 ID values 6 60 opening 6 11 6 50 specifying 6 53 DMA channel ID detecting 6 28 DMA configuration control register 6 13 6 58 10 46 DMA configuration Control word 6 59 DMaA controller circular transfer operating mode 6 16 DMA manager 6 4 identifying 6 41 inteface to 6 2 large descriptor chain mode 6 17 operating modes 6 13 single transfer operating mode 6 13 small descriptor mode 6 21 DMA manager API 6 33 defined 6 2 initializing 6 5 6 42 loopback submode 6 25 return codes 6 62 streaming submode 6 26 terminating 6 6 6 55 DMA peripheral map PMAP ID 10 57 DMAx_CONFIG register field values 6 63 dynamic power management power management PM module 3 2 dynamic power management registers configuring 3 21 INDEX E EBIU module API functions 4 6 controling the configuration of 4 25 defined 4 1 enumerations 4 19 initialization values 4 13 initializing 4 13 public data types 4 19 return codes 4 20 setting control values 4 25 EBIU_SDBCTL register EBCAW bits 4 30 EBSZ bits 4 30 setting 4 13 EBIU_SDGCTL register adi_ebiu_AdjustSDRAM function 4 8 CDDBG bit 4 36 EBUFE bit 4 34 EMREN bit 4 33 FBBRW bit 4 36 PASR bits 4 33 PSM bit 4 35 PUPSD
29. ADI PWR COMMAND Available Commands Cont Command Associated Data Value ADI PUR CMD SET VR WAKE An ADI PWR VR WAKE value specifying if the voltage regulator is to be awakened from power down upon an interrupt from the RTC or a low going edge on the RESET pin see ADI PWR VR WAKE on page 3 70 ADI PUR CMD SET VR PHYME An ADI PWR VR PHYWE enumeration value indi cating whether to enable disable the PHYWE bit ADSP BF534 ADSP BF536 and ADSP BF537 cores only see ADI_PWR_VR_PHYWE on page 3 69 ADI PUR CMD SET VR CANME An ADI PWR VR CANWE enumeration value indi cating whether to enable or disable the CANWE bit ADSP BF534 ADSP BF536 and ADSP BF537 cores only see ADI PWR VR CANWE on page 3 64 ADI PUR CMD SET VR CLKBUFOE An ADI PWR VR CLKBUFOE enumeration value indicating whether to enable or disable the CLKBUFOE bit ADSP BF534 ADSP BF536 and ADSP BF537 cores only see ADI PWR VR CLKBUFOF on page 3 66 ADI PUR CMD SET VR CKELOW An ADI PUR VR CKELOW enumeration value indicating whether to enable or disable the CKELOW bit ADSP BF534 ADSP BF536 and ADSP BF537 cores only see ADI PWR VR CKELOW on page 3 65 Commands valid only when passed to the adi pwr Control function ADI PUR CMD GET VDDINT An ADI PWR VLEV value containing the maxi mum core voltage level see ADI PWR VLEV on page 3 63
30. Application Interface Each system service exports an application programming interface API that defines the interface into that service Application software makes calls into the API of the system service to access the functionality that is to be controlled Each API is designed to be called using the standard calling interface of the development toolset s C run time model The API of each service can be called by any C or assembly language program that adheres to the call ing conventions and register usage of the C run time model In addition to the application software using the API to make calls into a system service some system services make calls into the API of other sys tem services For the most part each service operates independently of the other services however redundancies are eliminated by allowing one ser vice to access the functionality of another service For example should the application need to be notified when a DMA descriptor has completed processing and the application has requested deferred callbacks In this case the DMA Management service invokes the deferred callback service to effect the callback into the application Another example of combined operation between services is in the case of the power management and EBIU services Assume that the system has SDRAM and the application needs to conserve power by turning down VisualDSP 4 5 Device Drivers and System 1 7 Services Manual for Blackfin Pro
31. DCB COMMAND kind void value ADI DCB COMMAND PAIR For valid values for the kind field refer to ADI_DCB_COMMAND For example the following command could be sent to the DCB manager to flush all callbacks in the queue ADI DCB COMMAND PAIR CMD ADI DCB CMD FLUSH QUEUE NULL 5 28 VisualDSP 4 5 Device Drivers and System Services Manual for Blackfin Processors Deferred Callback Manager ADI DCB COMMAND The ADI DCB COMMAND is used to control the DCB manager s queue server This data type is used in an ADI DCB COMMAND PAIR couplet to change a configuration value in calls to adi dcb Control Command Associated Data Value ADI DCB CMD END This command defines the end of a table of command pairs ADI DCB CMD PAIR This command is used to tell adi dcb Control that a single command pair is being passed ADI DCB CMD TABLE This command is used to tell adi dcb Control that a table of command pairs is being passed ADI DCB CMD FLUSH QUEUE The address of the callback function for which all matching queue entries are cleared from the queue regardless of priority VisualDSP 4 5 Device Drivers and System 5 29 Services Manual for Blackfin Processors Public Data Types and Macros ADI DCB ENTRY HDR The ADI DCB ENTRY HDR structure is provided to interface with the under lying RTOS through the adi dcb Forward function refer to adi dcb Forward
32. DMA DATA MODE DESCRIPTOR ARRAY This is an array of descriptors ADI DMA DATA MODE DESCRIPTOR SMALL This is a chain of small descriptors ADI DMA DATA MODE DESCRIPTOR LARGE This is a chain of large descriptors ADI DMA PMAP The ADI DMA PMAP enumeration defines each of the DMA supported on chip peripherals of the processor This value is used to detect and set the mappings of on chip peripherals to DMA channels using the adi dma GetMapping and adi_dma_SetMapping functions The specific enumeration values are dependent on the specific processor being targeted VisualDSP 4 5 Device Drivers and System Services Manual for Blackfin Processors 6 61 Public Data Structures Enumerations and Macros ADI DMA RESULT All public DMA manager functions return a result code of the enumera tion type ADI DMA RESULT Possible values are ADI DMA RESULT SUCCESS Generic success is reported ADI DMA RESULT FAIL Generic failure is reported ADI DMA RESULT BAD DEVICE A bad device information was received ADI_DMA_RESULT_BAD_HANDLE A bad device handle was encountered ADI_DMA_RESULT_BAD_DESCRIPTOR A bad descriptor was encountered ADI_DMA_RESULT_BAD_MODE A bad channel mode was encountered ADI_DMA_RESULT_IN_USE Channel is already in use ADI_DMA_RESULT_ALREADY_RUNNING DMA is already running ADI DMA RESULT NO BUFFER Channel has no buffer ADI
33. DMA Manager adi dma MemoryClose Description This function closes down a memory DMA stream freeing up all resources used by the memory stream Prototype ADI DMA RESULT adi dma MemoryClose ADI DMA STREAM HANDLE StreamHandle u32 WaitFlag jts Arguments StreamHandle This is the handle to the DMA memory stream WaitFlag If set to TRUE 1 this argument instructs the DMA man ager to wait for ongoing transfers to complete before closing down the memory stream otherwise if set to FALSE 0 the channel is closed immediately terminating any transfers in progress Return Value The function returns ADI DMA RESULT SUCCESS if successful Any other value indicates an error Possible errors include ADI DMA RESULT BAD HANDLE The StreamHandle parameter does not point to a valid memory stream VisualDSP 4 5 Device Drivers and System 6 43 Services Manual for Blackfin P

ANALOG DEVICES VisualDSP 4.5 Device Drivers System Services Manual for Blackfin Processors (Revision 2.1 April 2006)

Contents