ANALOG DEVICES W4.0 Service Manual

W4.0

Device Drivers and System Services Manual

for Blackfin® Processors

Analog Devices, Inc.
One Technology Way
Norwood, Mass. 02062-9106

Revision 1.0, February 2005

Part Number

82-000430-01

a

Copyright Information

©2005 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 of This Manual ................................................................ xvii

Intended Audience ........................................................................ xvii

Manual Contents Description ...................................................... xviii

Technical or Customer Support ...................................................... xix

Product Information ...................................................................... xix

MyAnalog.com .......................................................................... xx

Processor Product Information ................................................... xx

Related Documents .................................................................. xxi

Online Technical Documentation ............................................. xxi

Accessing Documentation From VisualDSP++ ..................... xxii

Accessing Documentation From Windows ........................... xxii

Accessing Documentation From the Web ........................... xxiii

Printed Manuals .................................................................... xxiii

VisualDSP++ Documentation Set ....................................... xxiv

Hardware Tools Manuals .................................................... xxiv

Processor Manuals .............................................................. xxiv

Data Sheets ........................................................................ xxiv

Notation Conventions ................................................................... xxv

Device Drivers and System Services Manual for Blackfin Processors iii

CONTENTS

INTRODUCTION

System Services Overview ............................................................. 1-2

Application Interface ............................................................... 1-5

Dependencies .......................................................................... 1-6

Initialization ........................................................................... 1-7

Termination ............................................................................ 1-9

System Services Directory and File Structure .......................... 1-10

Accessing the System Services API ..................................... 1-10

Linking in the System Services Library .............................. 1-12

Rebuilding the System Services Library ............................. 1-13

Examples .............................................................................. 1-15

Device Driver Overview .............................................................. 1-15

Application Interface ............................................................. 1-16

Device Driver Architecture .................................................... 1-17

Interaction with System Services ....................................... 1-18

Initialization ......................................................................... 1-19

Termination .......................................................................... 1-19

Device Driver Directory and File Structure ............................ 1-20

Accessing the Device Driver API ....................................... 1-20

Linking in the Device Driver Library ................................ 1-22

Rebuilding the Device Driver Library ................................ 1-23

Examples .............................................................................. 1-25

iv Device Drivers and System Services Manual for Blackfin Processors

CONTENTS

INTERRUPT MANAGER

Introduction ................................................................................. 2-2

Initialization ................................................................................. 2-4

Termination .................................................................................. 2-5

Core Event Controller Functions ................................................... 2-6

adi_int_CECHook() ................................................................ 2-6

adi_int_CECUnhook() ............................................................ 2-8

Interrupt Handlers .................................................................. 2-8

System Interrupt Controller Functions .......................................... 2-9

adi_int_SICDisable() ............................................................. 2-10

adi_int_SICEnable() .............................................................. 2-10

adi_int_SICGetIVG() ............................................................ 2-10

adi_int_SICInterruptAsserted() ............................................. 2-11

adi_int_SICSetIVG() ............................................................. 2-11

adi_int_SICWakeup() ............................................................ 2-11

Protecting Critical Regions .......................................................... 2-12

Modifying IMASK ...................................................................... 2-14

Examples .................................................................................... 2-15

File Structure .............................................................................. 2-16

Interrupt Manager API Reference ................................................ 2-17

Notation Conventions ........................................................... 2-17

adi_int_Init ........................................................................... 2-18

adi_int_Terminate ................................................................. 2-19

adi_int_CECHook ................................................................ 2-20

Device Drivers and System Services Manual for Blackfin Processors v

CONTENTS

adi_int_CECUnhook ............................................................ 2-22

adi_int_ClearIMaskBits ........................................................ 2-24

adi_int_EnterCriticalRegion .................................................. 2-26

adi_int_ExitCriticalRegion .................................................... 2-28

adi_int_SICDisable ............................................................... 2-29

adi_int_SICEnable ................................................................ 2-30

adi_int_SICGetIVG .............................................................. 2-31

adi_int_SICInterruptAsserted ................................................ 2-32

adi_int_SICSetIVG .............................................................. 2-33

adi_int_SetIMaskBits ............................................................ 2-34

adi_int_SICWakeup .............................................................. 2-36

POWER MANAGEMENT MODULE

Introduction ................................................................................. 3-2

PM Module Operation – Getting Started ...................................... 3-3

Power Management API Reference ................................................ 3-6

Notation Conventions ............................................................. 3-6

adi_pwr_AdjustFreq ................................................................ 3-7

adi_pwr_Control .................................................................... 3-9

adi_pwr_GetConfigSize ........................................................ 3-11

adi_pwr_GetFreq .................................................................. 3-12

adi_pwr_GetPowerMode ....................................................... 3-13

adi_pwr_GetPowerSaving ...................................................... 3-13

adi_pwr_Init ......................................................................... 3-14

adi_pwr_LoadConfig ............................................................ 3-18

vi Device Drivers and System Services Manual for Blackfin Processors

CONTENTS

adi_pwr_Reset ....................................................................... 3-19

adi_pwr_SaveConfig .............................................................. 3-20

adi_pwr_SetFreq ................................................................... 3-21

adi_pwr_SetMaxFreqForVolt ................................................. 3-23

adi_pwr_SetPowerMode ........................................................ 3-24

adi_pwr_SetVoltageRegulator ................................................ 3-26

Public Data Types and Enumerations ........................................... 3-30

ADI_PWR_COMMAND ..................................................... 3-31

ADI_PWR_COMMAND_PAIR ........................................... 3-35

ADI_PWR_CSEL ................................................................. 3-35

ADI_PWR_DF ..................................................................... 3-36

ADI_PWR_EZKIT ............................................................... 3-37

ADI_PWR_INPUT_DELAY ................................................. 3-37

ADI_PWR_OUTPUT_DELAY ............................................. 3-37

ADI_PWR_MODE .............................................................. 3-38

ADI_PWR_PACKAGE_KIND ............................................. 3-39

ADI_PWR_PCC133_COMPLIANCE .................................. 3-40

ADI_PWR_PROC_KIND .................................................... 3-41

ADI_PWR_RESULT ............................................................ 3-42

ADI_PWR_SSEL .................................................................. 3-44

ADI_PWR_VDDEXT .......................................................... 3-45

ADI_PWR_VLEV ................................................................. 3-46

ADI_PWR_VR_CANWE ..................................................... 3-47

ADI_PWR_VR_CKELOW ................................................... 3-48

Device Drivers and System Services Manual for Blackfin Processors vii

CONTENTS

ADI_PWR_VR_CLKBUFOE ............................................... 3-49

ADI_PWR_VR_FREQ ......................................................... 3-50

ADI_PWR_VR_GAIN ......................................................... 3-50

ADI_PWR_VR_PHYWE ..................................................... 3-50

ADI_PWR_VR_WAKE ........................................................ 3-51

PM Module Macros .................................................................... 3-51

EXTERNAL BUS INTERFACE UNIT MODULE

Introduction ................................................................................. 4-2

Using the EBIU Module ............................................................... 4-3

EBIU API Reference ..................................................................... 4-6

Notation Conventions ............................................................. 4-6

adi_ebiu_AdjustSDRAM ......................................................... 4-7

adi_ebiu_Control .................................................................... 4-8

adi_ebiu_GetConfigSize ........................................................ 4-11

adi_ebiu_Init ........................................................................ 4-12

adi_ebiu_LoadConfig ............................................................ 4-16

adi_ebiu_SaveConfig ............................................................ 4-17

Public Data Types and Enumerations .......................................... 4-18

ADI_EBIU_RESULT ........................................................... 4-19

ADI_EBIU_SDRAM_BANK_VALUE .................................. 4-21

ADI_EBIU_TIME ................................................................ 4-22

ADI_EBIU_TIMING_VALUE ............................................. 4-23

Setting Control Values in the EBIU Module ................................ 4-24

ADI_EBIU_COMMAND .................................................... 4-24

viii Device Drivers and System Services Manual for Blackfin Processors

CONTENTS

ADI_EBIU_COMMAND_PAIR ........................................... 4-28

Command Value Enumerations ............................................. 4-28

ADI_EBIU_SDRAM_EZKIT ........................................... 4-28

ADI_EBIU_SDRAM_ENABLE ........................................ 4-28

ADI_EBIU_SDRAM_BANK_SIZE .................................. 4-29

ADI_EBIU_SDRAM_BANK_COL_WIDTH ................... 4-29

ADI_EBIU_SDRAM_MODULE_TYPE .......................... 4-30

ADI_EBIU_CMD_SET_SDRAM_SCTLE ....................... 4-31

ADI_EBIU_SDRAM_EMREN ......................................... 4-31

ADI_EBIU_SDRAM_PASR ............................................. 4-32

ADI_EBIU_SDRAM_TCSR ............................................. 4-32

ADI_EBIU_SDRAM_SRFS .............................................. 4-33

ADI_EBIU_SDRAM_EBUFE .......................................... 4-33

ADI_EBIU_SDRAM_PUPSD .......................................... 4-33

ADI_EBIU_SDRAM_PSM ............................................... 4-34

ADI_EBIU_SDRAM_FBBRW .......................................... 4-34

ADI_EBIU_SDRAM_CDDBG ........................................ 4-35

DEFERRED CALLBACK MANAGER

Introduction ................................................................................. 5-2

Using the Deferred Callback Manager ........................................... 5-3

Interoperability With an RTOS ..................................................... 5-7

adi_dcb_Forward ..................................................................... 5-8

adi_dcb_RegisterISR ............................................................... 5-9

Handling Critical Regions within Callbacks ........................... 5-10

Device Drivers and System Services Manual for Blackfin Processors ix

CONTENTS

DCB Manager API Reference ...................................................... 5-10

Notation Conventions ........................................................... 5-10

adi_dcb_Close ...................................................................... 5-12

adi_dcb_Control ................................................................... 5-13

adi_dcb_Init ......................................................................... 5-16

adi_dcb_Open ...................................................................... 5-18

adi_dcb_Post ........................................................................ 5-20

adi_dcb_Remove ................................................................... 5-22

adi_dcb_Terminate ............................................................... 5-23

Public Data Types and Macros .................................................... 5-24

ADI_DCB_CALLBACK_FN ................................................ 5-24

ADI_DCB_COMMAND_PAIR ........................................... 5-25

ADI_DCB_COMMAND ..................................................... 5-26

ADI_DCB_ENTRY_HDR ................................................... 5-26

ADI_DCB_RESULT ............................................................ 5-27

DMA MANAGER

Introduction ................................................................................. 6-1

Theory of Operation .................................................................... 6-2

Overview ................................................................................ 6-3

Initialization ........................................................................... 6-3

Termination ............................................................................ 6-5

Memory DMA and Peripheral DMA ....................................... 6-5

Controlling Memory Streams .................................................. 6-6

Opening Memory Streams .................................................. 6-6

x Device Drivers and System Services Manual for Blackfin Processors

Memory Transfers ............................................................... 6-7

One-Dimensional Transfers (Linear Transfers) ................. 6-8

Two-Dimensional Transfers ............................................. 6-9

Closing Memory Streams .................................................. 6-10

Controlling DMA Channels .................................................. 6-10

Opening DMA Channels .................................................. 6-10

Operating Modes .......................................................... 6-11

Configuring a DMA Channel ............................................ 6-21

Closing a DMA Channel ................................................... 6-21

Transfer Completions ............................................................ 6-22

Polling .............................................................................. 6-22

Callbacks .......................................................................... 6-22

Memory Stream Callbacks ............................................. 6-23

Circular Transfer Callbacks ............................................ 6-23

Descriptor Callbacks ..................................................... 6-24

Descriptor Based Submodes ................................................... 6-24

Loopback Submode ........................................................... 6-24

Streaming Submode .......................................................... 6-25

DMA Channel to Peripheral Mapping ................................... 6-26

Sensing a Mapping ............................................................ 6-27

Setting a Mapping ............................................................. 6-27

Interrupts .............................................................................. 6-27

Hooking Interrupts ........................................................... 6-28

Unhooking Interrupts ....................................................... 6-28

Device Drivers and System Services Manual for Blackfin Processors xi

Two-Dimensional DMA ........................................................ 6-29

DMA Manager API Reference ..................................................... 6-32

Notation Conventions ........................................................... 6-32

adi_dma_Buffer .................................................................... 6-34

adi_dma_Control .................................................................. 6-36

adi_dma_Close ..................................................................... 6-39

adi_dma_GetMapping .......................................................... 6-40

adi_dma_Init ........................................................................ 6-41

adi_dma_MemoryClose ........................................................ 6-42

adi_dma_MemoryCopy ........................................................ 6-43

adi_dma_MemoryCopy2D .................................................... 6-45

adi_dma_MemoryOpen ........................................................ 6-47

adi_dma_Open ..................................................................... 6-49

adi_dma_Queue ................................................................... 6-51

adi_dma_SetMapping ........................................................... 6-52

adi_dma_Terminate .............................................................. 6-53

Public Data Structures, Enumerations and Macros ....................... 6-53

Data Types ............................................................................ 6-54

ADI_DMA_CHANNEL_HANDLE ................................. 6-54

ADI_DMA_DESCRIPTOR_UNION /

ADI_DMA_DESCRIPTOR_HANDLE ......................... 6-54

ADI_DMA_STREAM_HANDLE .................................... 6-55

Data Structures ..................................................................... 6-55

ADI_DMA_2D_TRANSFER ........................................... 6-56

ADI_DMA_CONFIG_REG ............................................ 6-56

xii Device Drivers and System Services Manual for Blackfin Processors

ADI_DMA_DESCRIPTOR_ARRAY ................................ 6-56

ADI_DMA_DESCRIPTOR_LARGE ................................ 6-57

ADI_DMA_DESCRIPTOR_SMALL ................................ 6-57

General Enumerations ........................................................... 6-57

ADI_DMA_CHANNEL_ID ............................................ 6-58

ADI_DMA_EVENT ......................................................... 6-58

ADI_DMA_MODE ......................................................... 6-58

ADI_DMA_PMAP ........................................................... 6-59

ADI_DMA_RESULT ....................................................... 6-59

ADI_DMA_STREAM_ID ................................................ 6-59

ADI_DMA_CONFIG_REG Field Values .............................. 6-61

ADI_DMA_DMA2D ....................................................... 6-61

ADI_DMA_DI_EN .......................................................... 6-61

ADI_DMA_DI_SEL ......................................................... 6-61

ADI_DMA_EN ................................................................ 6-61

ADI_DMA_WDSIZE ....................................................... 6-61

ADI_DMA_WNR ............................................................ 6-62

DMA Commands .................................................................. 6-62

DEVICE DRIVER MANAGER

Device Driver Model Overview ..................................................... 7-3

Using the Device Manager ............................................................ 7-5

Device Manager Overview ....................................................... 7-6

Theory of Operation ............................................................... 7-6

Data ................................................................................... 7-7

Device Drivers and System Services Manual for Blackfin Processors xiii

Initializing the Device Manager .......................................... 7-8

Termination ....................................................................... 7-9

Opening a Device ............................................................... 7-9

Configuring a Device ........................................................ 7-10

Dataflow Method ......................................................... 7-11

Enabling Dataflow ........................................................ 7-14

Providing Buffers to a Device ............................................ 7-14

Closing a Device ............................................................... 7-16

Callbacks .......................................................................... 7-16

Initialization Sequence ...................................................... 7-16

Stackable Drivers .............................................................. 7-17

Device Manager Design .............................................................. 7-18

Device Manager API Description ........................................... 7-18

Memory Usage Macros ..................................................... 7-19

Handles ............................................................................ 7-20

Dataflow Enumerations .................................................... 7-20

Command IDs ................................................................. 7-20

Callback Events ................................................................ 7-21

Return Codes ................................................................... 7-21

Circular Buffer Callback Options ...................................... 7-21

Buffer Data Types ............................................................. 7-21

Physical Driver Entry Point .............................................. 7-22

API Function Definitions ................................................. 7-22

Device Manager Code ........................................................... 7-23

xiv Device Drivers and System Services Manual for Blackfin Processors

Data Structures ................................................................. 7-23

Static Data ........................................................................ 7-23

Static Function Declarations .............................................. 7-23

API Functional Description ............................................... 7-24

adi_dev_Init ................................................................. 7-24

adi_dev_Open .............................................................. 7-24

adi_dev_Close ............................................................... 7-25

adi_dev_Read ............................................................... 7-26

adi_dev_Write ............................................................... 7-27

adi_dev_Control ........................................................... 7-27

Static Functions ................................................................ 7-31

PDDCallback ............................................................... 7-31

DMACallback ............................................................... 7-31

PrepareBufferList .......................................................... 7-32

SetDataflow .................................................................. 7-34

Physical Driver Design ................................................................ 7-35

Physical Driver Design Overview ........................................... 7-35

Physical Device Driver API Description ................................. 7-37

Physical Driver Include File (“xxx.h”) ..................................... 7-38

Extensible Definitions ....................................................... 7-38

ADI_DEV_PDD_ENTRY_POINT .................................. 7-40

Physical Driver Source (“xxx.c”) ............................................. 7-40

adi_pdd_Open .................................................................. 7-41

adi_pdd_Control .............................................................. 7-42

Device Drivers and System Services Manual for Blackfin Processors xv

adi_pdd_Read .................................................................. 7-44

adi_pdd_Write ................................................................. 7-45

adi_pdd_Close ................................................................. 7-46

Device Manager API Reference ................................................... 7-47

Notation Conventions ........................................................... 7-47

adi_dev_Close ....................................................................... 7-48

adi_dev_Control ................................................................... 7-49

adi_dev_Init ......................................................................... 7-50

adi_dev_Open ...................................................................... 7-52

adi_dev_Read ....................................................................... 7-54

adi_dev_Terminate ................................................................ 7-55

adi_dev_Write ...................................................................... 7-56

Physical Driver API Reference ..................................................... 7-57

Notation Conventions ........................................................... 7-57

adi_pdd_Close ...................................................................... 7-58

adi_pdd_Control .................................................................. 7-59

adi_pdd_Open ...................................................................... 7-60

adi_pdd_Read ....................................................................... 7-62

adi_pdd_Write ...................................................................... 7-63

Examples .................................................................................... 7-64

INDEX

xvi Device Drivers and System Services Manual for Blackfin Processors

PREFACE

Thank you for using Analog Devices, Inc. development software for
Analog Devices embedded processors.

Purpose of This Manual

The Device Drivers and System Services Manual for Blackfin Processors con­tains information about the Analog Devices Device Driver Model and
System Services library suite. Included are architectural descriptions of the
device driver design, and each of the System Service components. Also
included is a description of the APIs into each library.

Intended Audience

The primary audience for this manual is a programmer who is familiar
with Analog Devices processors. This manual assumes that the audience
has a working knowledge of the appropriate processor architecture and
instruction set. Programmers who are unfamiliar with Analog Devices
processors can use this manual, but should supplement it with other texts
(such as the appropriate hardware reference and programming reference
manuals) that describe your target architecture.

Device Drivers and System Services Manual for Blackfin Processors xvii

Manual Contents Description

Manual Contents Description

This manual contains:

• Chapter 1, “Introduction”
provides an overview of System Services and Device Drivers

• Chapter 2, “Interrupt Manager”
describes the System Interrupt Controller (SIC) Manager that sup­ports the general-purpose interrupt events

• Chapter 3, “Power Management Module”
describes the Power Management module that supports Dynamic
Power Management of Blackfin processors

• Chapter 4, “External Bus Interface Unit Module”
describes the External Bus Interface Unit (EBIU) module that is
used to enable the Power Management module to manage the
SDRAM Controller operation

• Chapter 5, “Deferred Callback Manager”
describes the Deferred Callback Manager that is used by the appli­cation developer to effectively execute function calls

• Chapter 6, “DMA Manager”
describes Direct Memory Access (DMA) Manager API

• Chapter 7, “Device Driver Manager”
describes the device driver model used to control devices, both
internal and external, to ADI processors

xviii Device Drivers and System Services Manual for Blackfin Processors

Technical or Customer Support

You can reach Analog Devices, Inc. Customer Support in the following
ways:

• Visit the Embedded Processing and DSP products Web site at

http://www.analog.com/processors/technicalSupport

• E-mail tools questions to

[e-mail]

• E-mail processor questions to

[e-mail]

• Phone questions to 1-800-ANALOGD

• Contact your Analog Devices, Inc. local sales office or authorized
distributor

Preface

• Send questions by mail to:

Analog Devices, Inc.
One Technology Way
P.O. Box 9106
Norwood, MA 02062-9106
USA

Product Information

You can obtain product information from the Analog Devices Web site,
from the product CD-ROM, or from the printed publications (manuals).

Analog Devices is online at www.analog.com. Our Web site provides infor­mation about a broad range of products—analog integrated circuits,
amplifiers, converters, and digital signal processors.

Device Drivers and System Services Manual for Blackfin Processors xix

Product Information

MyAnalog.com

MyAnalog.com is a free feature of the Analog Devices Web site that allows

customization of a Web page to display only the latest information on
products you are interested in. You can also choose to receive weekly
E-mail notification containing updates to the Web pages that meet your
interests.
sheets, code examples, and more.

Registration:

Visit www.myanalog.com to sign up. Click Register to use MyAnalog.com.
Registration takes about five minutes and serves as means for you to select
the information you want to receive.

If you are already a registered user, just log on. Your user name is your
E-mail address.

MyAnalog.com provides access to books, application notes, data

Processor Product Information

For information on embedded processors and DSPs, visit our Web site at

www.analog.com/processors, which provides access to technical publica-

tions, data sheets, application notes, product overviews, and product
announcements.

xx Device Drivers and System Services Manual for Blackfin Processors

Preface

You may also obtain additional information about Analog Devices and its
products in any of the following ways.

• E-mail questions or requests for information to

[e-mail]

• Fax questions or requests for information to

1-781-461-3010 (North America)
089/76 903-557 (Europe)

• Access the FTP Web site at

ftp ftp.analog.com or ftp 137.71.23.21
ftp://ftp.analog.com

Related Documents

For software/tools information, refer to VisualDSP++ user’s documenta­tion available online and in printed forms.

For hardware information, refer to your processors’s hardware reference,
programming reference, or data sheet. All documentation is available
online. Most documentation is available in printed form.

Visit the Technical Library Web site to access all processor and tools man­uals and data sheets:

http://www.analog.com/processors/resources/technicalLibrary

Online Technical Documentation

Online documentation includes the VisualDSP++ Help system, software
tools manuals, hardware tools manuals, processor manuals, Dinkum
Abridged C++ library, and Flexible License Manager (FlexLM) network
license manager software documentation. You can easily search across the

Device Drivers and System Services Manual for Blackfin Processors xxi

Product Information

entire VisualDSP++ documentation set for any topic of interest using the
Search function of VisualDSP++ Help system. For easy printing, supple
mentary .PDF files of most manuals are also provided.

Each documentation file type is described as follows.

File Description

.CHM Help system files and manuals in Help format

-

.HTM or
.HTML

.PDF VisualDSP++ and processor manuals in Portable Documentation Format (PDF).

Dinkum Abridged C++ library and FlexLM network license manager software
documentation. Viewing and printing the .HTML files requires a browser, such as
Internet Explorer 4.0 (or higher).

Viewing and printing the
Reader (4.0 or higher).

.PDF files requires a PDF reader, such as Adobe Acrobat

Access the online documentation from the VisualDSP++ environment,
Windows

®

Explorer, or the Analog Devices Web site.

Accessing Documentation From VisualDSP++

From the VisualDSP++ environment:

• Access VisualDSP++ online Help from the Help menu’s Contents,
Search, and Index commands.

• Open online Help from context-sensitive user interface items (tool­bar buttons, menu commands, and windows).

Accessing Documentation From Windows

In addition to any shortcuts you may have constructed, there are many
ways to open VisualDSP++ online Help or the supplementary documenta
tion from Windows.

-

xxii Device Drivers and System Services Manual for Blackfin Processors

Preface

Help system files (.CHM) are located in the Help folder of VisualDSP++
environment. The

.PDF files are located in the Docs folder of your

VisualDSP++ installation CD-ROM. The Docs folder also contains the
Dinkum Abridged C++ library and the FlexLM network license manager
software documentation.

Using Windows Explorer

• Double-click the vdsp-help.chm file, which is the master Help sys­tem, to access all the other .CHM files.

• Open your VisualDSP++ installation CD-ROM and double-click
any file that is part of the VisualDSP++ documentation set.

Using the Windows Start Button

• Access VisualDSP++ online Help by clicking the Start button and
choosing Programs, Analog Devices, VisualDSP++, and
VisualDSP++ Documentation.

Accessing Documentation From the Web

Download manuals in PDF format at the following Web site:

http://www.analog.com/processors/resources/technicalLibrary/manuals

Select a processor family and book title. Download archive (.ZIP) files, one
for each manual. Use any archive management software, such as WinZip,
to decompress downloaded files.

Printed Manuals

For general questions regarding literature ordering, call the Literature
Center at 1-800-ANALOGD (1-800-262-5643) and follow the prompts.

Device Drivers and System Services Manual for Blackfin Processors xxiii

Product Information

VisualDSP++ Documentation Set

To purchase VisualDSP++ manuals, call 1-603-883-2430. The manuals
may be purchased only as a kit.

If you do not have an account with Analog Devices, you are referred to
Analog Devices distributors. For information on our distributors, log onto

http://www.analog.com/salesdir/continent.asp.

Hardware Tools Manuals

To purchase EZ-KIT Lite™ and In-Circuit Emulator (ICE) manuals, call
1-603-883-2430. The manuals may be ordered by title or by product
number located on the back cover of each manual.

Processor Manuals

Hardware reference and instruction set reference manuals may be ordered
through the Literature Center at 1-800-ANALOGD (1-800-262-5643),
or downloaded from the Analog Devices Web site. Manuals may be
ordered by title or by product number located on the back cover of each
manual.

Data Sheets

All data sheets (preliminary and production) may be downloaded from the
Analog Devices Web site. Only production (final) data sheets (Rev. 0, A,
B, C, and so on) can be obtained from the Literature Center at
1-800-ANALOGD (1-800-262-5643); they also can be downloaded from
the Web site.

To have a data sheet faxed to you, call the Analog Devices Faxback System
at 1-800-446-6212. Follow the prompts and a list of data sheet code
numbers will be faxed to you. If the data sheet you want is not listed,
check for it on the Web site.

xxiv Device Drivers and System Services Manual for Blackfin Processors

Notation Conventions

Text conventions used in this manual are identified and described as
follows.

Example Description

Preface

Close command
(File menu)

{this | that} Alternative required items in syntax descriptions appear within curly

[this | that] Optional items in syntax descriptions appear within brackets and

[this,…] Optional item lists in syntax descriptions appear within brackets

.SECTION Commands, directives, keywords, and feature names are in text with

filename Non-keyword placeholders appear in text with italic style format.

L

a

Titles in reference sections indicate the location of an item within the
VisualDSP++ environment’s menu system (for example, the Close
command appears on the File menu).

brackets and separated by vertical bars; read the example as

that. One or the other is required.

separated by vertical bars; read the example as an optional this or

.

that

delimited by commas and terminated with an ellipse; read the example
as an optional comma-separated list of

letter gothic font.

Note: For correct operation, ...
A Note provides supplementary information on a related topic. In the
online version of this book, the word Note appears instead of this

symbol.

Caution: Incorrect device operation may result if ...
Caution: Device damage may result if ...

A Caution identifies conditions or inappropriate usage of the product
that could lead to undesirable results or product damage. In the online
version of this book, the word Caution appears instead of this symbol.

this.

this or

Warn in g: Injury to device users may result if ...
A Warning identifies conditions or inappropriate usage of the product

[

that could lead to conditions that are potentially hazardous for devices
users. In the online version of this book, the word Wa rnin g appears
instead of this symbol.

Device Drivers and System Services Manual for Blackfin Processors xxv

Notation Conventions

L

Additional conventions, which apply only to specific chapters, may
appear throughout this document.

xxvi Device Drivers and System Services Manual for Blackfin Processors

1 INTRODUCTION

This manual describes the System Services and Device Driver architecture
for Analog Devices processors.

The System Services form a collection of functions that are commonly
found in embedded systems. Each system service focuses on a specific set
of functionality such as Direct Memory Access (DMA), Power Manage
ment (PM), Interrupt Control (IC), and so on. Collectively, the system
services provide a wealth of pre-built, optimized code that simplifies soft
ware development for users, allowing them to get their Blackfin
processor-based designs to market more quickly.

The Device Driver model provides a simple, clean and familiar interface
into device drivers for Blackfin processors. The primary objective of the
device driver model is to create a concise, effective and easy to use inter
face through which applications can communicate with device drivers.
Secondarily, the model and device manager software, significantly simpli­fies the development of device drivers, making it very straightforward for
the development of new device drivers.

-

-

-

Device Drivers and System Services Manual for Blackfin Processors 1-1

System Services Overview

System Services Overview

The current revision of the System Services library consists of five services:

• Interrupt Control Service - The Interrupt Control service allows
the application to control and leverage the event and interrupt pro
cessing of the processor more effectively. Specific functionality
allows the application to:

• Set and detect the mappings of the interrupt priority levels
to peripherals.

• Use standard ‘C’ functions as interrupt handlers.

• Hook and unhook multiple interrupt handlers to the same
interrupt priority level using both nesting and non-nesting
capabilities.

-

• Detect if a system interrupt is being asserted.

• Protect and unprotect critical regions of code in a portable
manner.

• Power Management Service - The Power Management service
allows the application to control the Dynamic Power Management
capabilities of the Blackfin processor. Specific functionality allows
the application to:

• Set core and system clock operating frequencies via a
function call.

• Set and detect the internal voltage regulator settings.

• Transition the processor among the various operat­ing modes including, Full-On, Active, Sleep, and so
on.

1-2 Device Drivers and System Services Manual for Blackfin Processors

Introduction

• External Bus Interface Unit Control Service (EBIU) - The EBIU
Control service provides a collection of routines to set up the exter
nal interfaces of the Blackfin processor, including the SDRAM
controller. This functionality enables users to:

• Adjust SDRAM refresh and timing rates to optimal values
for given system clock frequencies.

• Set individual bus interface settings.

• Complete single function setup for known configurations,
such as the Blackfin EZ-Kits.

• Deferred Callback Service - The Deferred Callback service allows
the application to be notified of asynchronous events outside of
high priority interrupt service routines. Using deferred callbacks
typically improves the overall I/O capacity of the system while at
the same time reducing interrupt latency. Specific functionality
allows the application to:

-

• Define how many callbacks can be pending at any point in
time.

• Define the interrupt priority level at which the callback ser­vice executes.

• Create multiple callback services, each operating at a differ­ent interrupt priority level.

• Post callbacks to a callback service with a relative priority
among all other callbacks posted to the same callback
service.

• DMA Management Service - The DMA Management service pro­vides access into the DMA controller of the Blackfin processor.
The DMA Management service allows the application to schedule

Device Drivers and System Services Manual for Blackfin Processors 1-3

System Services Overview

DMA operations, both peripheral and memory DMA, supporting
both linear and two-dimensional transfer types. Specific function
ality allows the application to:

• Set and detect the mapping of DMA channels to

peripherals.

• Configure individual DMA channels for inbound/outbound

traffic using circular (autobuffered) DMA or descriptor
based DMA.

• Command the DMA Manager to issue “live” or deferred

callbacks upon DMA completions.

• Queue descriptors, intermixing both linear and two-dimen-

sional transfers, on DMA channels.

• Enable the DMA Manager to loopback on descriptor chains

automatically.

-

• Continuously stream data into or out from a memory

stream or peripheral.

• Initiate linear and two-dimensional memory DMA transfers

with simple ‘C’ like,

memcpy-type functions.

• Device Manager - The device driver model is used to control
devices, both internal and external to Analog Devices processors.
Specific functionality allow the application to:

• Open and close devices used by the application.

• Configure and control devices.

• Receive and transmit data through the devices using a vari­ety of dataflow methods.

1-4 Device Drivers and System Services Manual for Blackfin Processors

Introduction

Application Interface

Each system service exports an API that defines the interface into that ser­vice. 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
the core and system clock frequencies. When the application calls the
Power Management service to lower the operating frequencies, the Power
Management service automatically invokes the EBIU service, which
adjusts the SDRAM refresh rate to compensate for the reduced system
clock frequency.

Device Drivers and System Services Manual for Blackfin Processors 1-5

System Services Overview

Figure 1-1 illustrates the current collection of system services and the API

interactions among them.

APPLICATION

DMA MANAGER

INTERRUPT CONTROLLER

POWER MANAGEMENT

CALLBACK MANAGER

EBIU CONTROL

Figure 1-1. System Services and API Interactions

Dependencies

With few constraints, applications can choose to use any individual service
or combination of services within their application. Applications do not
have to use each and every service. Further, each service does not need all
the resources associated with the system the service is controlling. For
example, the DMA Manager does not need control over each and every
DMA channel. The system can be configured for the DMA Manager to
control some channels, leaving the application or some other software to
control other DMA channels. (See the individual service chapters for more

1-6 Device Drivers and System Services Manual for Blackfin Processors

Introduction

information on each individual service.) There are however, some depen­dencies within the services of which the application developer should be
aware.

All the current services, except for the EBIU service, invoke the Interrupt
Control service for the management of interrupt processing. The DMA
Manager, Callback and Power Management Services each depend on the
IC service to manage interrupt processing for them.

If directed by the application to adjust SDRAM timing automatically, the
Power Management Service uses the EBIU Control Service to affect
SDRAM timing parameter changes when the power/operating speed pro
file of the processor is changed.

When configured to use deferred callbacks (as opposed to “live” or inter­rupt-time callbacks) the DMA Manager leverages the capabilities of the
Deferred Callback Service to provide deferred callbacks to the application.
When configured for “live” callbacks however, the DMA Manager does
not make use of the Deferred Callback Service.

-

The development toolset automatically determines these dependencies
and links into the executable only those services that are required by the
application. As each service is built as its own object file within the System
Services Library file, it is possible to further reduce code size of the final
executable by commanding the linker to eliminate any unused objects.
Refer to the development toolset documentation for more information.

Initialization

The API of each system service includes an initialization function that
must be called by the application, prior to accessing the other API func
tions of the service. All initialization functions of the services are of the

adi_xxx_Init() where xxx is the service name abbreviation. The ini-

form
tialization functions typically provide any data memory that is required of
the service and perform any setup and initialization of the systems being
controlled.

Device Drivers and System Services Manual for Blackfin Processors 1-7

-

System Services Overview

After reset, many applications need to adjust their operating frequency or
voltage and configure the external memories of the system. As such, the
Power Management and EBIU services are typically accessed when the
application starts. Since the Power Management service uses the function
ality of the Interrupt Manager to control the PLL, the Interrupt Manager
should be initialized prior to the Power Management service. It is also
preferable to initialize the Power Management service prior to the EBIU
service.

The remaining services, assuming the application is using some combina­tion of the remaining services, may require data memory as part of their
initialization. As some applications provide external memory to these ser­vices, this is another reason to initialize the Power Management and EBIU
services before any of the others.

In summary, most applications find the initialization sequence below opti­mal for their application. Any service not used by the application should
simply be omitted from the sequence.

-

1. Interrupt Control Service

2. Power Management Service

3. EBIU Service

4. Deferred Callback Service

5. DMA Manager Service

After all services that are to be used in the application have been initial­ized, the remaining API functions in any of the services may be called by
the application.

1-8 Device Drivers and System Services Manual for Blackfin Processors

Introduction

Termination

The API of each system service also includes a termination function that
may be called by the application if the functionality of a service is no
longer required. All termination functions of the services are of the form

adi_xxx_Terminate() where xxx is the service name abbreviation. Many

embedded systems run in an endless operating loop and never call the ter
mination function of a service. Applications that operate in endless loops
can save program memory by not calling the terminate functions.

Termination functions may make calls into other services whose function­ality they may be using. For example, the DMA Manager uses the services
of the Interrupt Control service to manage interrupts. As part of the pro
cess of terminating the DMA Manager Service, all DMA interrupt
handlers are unhooked via the Interrupt Control service. This means the
DMA Manager Service should be terminated prior to the Interrupt Con
trol Service being terminated.

-

-

-

The sequence described below ensures that services are closed in a logical
sequence and ensures that no service is closed unknowingly to some other
service. Most applications find the initialization sequence below optimal
for their application. Any service not used by the application should sim

-

ply be omitted from the sequence.

1. DMA Manager Service

2. Deferred Callback Service

3. EBIU Service

4. Power Management Service

5. Interrupt Control Service

After a service has been terminated, it must be re-initialized before any of
its functionality can be accessed again.

Device Drivers and System Services Manual for Blackfin Processors 1-9

System Services Overview

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

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 black-

fin/include/services directory in the compilers/assemblers

pre-processor search path. User source files accessing any of the System
Services APIs should simply include the

blackfin/include/services directory. User files do not need to include

any other files to use the System Services API.

blackfin directory tree.

services.h file, located in the

The System Services API and functionality are uniform and consistent
across all Blackfin processors, including all single and multi-core devices.
Application software does not have to change regardless of which Blackfin
processor is being targeted. For example application software running on a
single-core ADSP-BF533 processor can operate unchanged on a
multi-core ADSP-BF561 processor.

In order to provide this consistent API to the application, the System Ser­vices API needs to be aware of the specific processor variant being
targeted. The user should ensure that the processor definition macro for
the processor variant being targeted is defined when including the

vices.h include file.

ser-

1-10 Device Drivers and System Services Manual for Blackfin Processors

Introduction

The VisualDSP++ toolset automatically sets the processor definition
macro when building projects. Application developers using the Visu
alDSP++ toolset need do nothing further to ensure the processor
definition macro is defined.

Application developers using other toolsets, however, should ensure the
processor definition macro is appropriately defined. The
enumerates the specific processor variants that are supported. These pro
cessor variants include:

__ADSPBF531__ The ADSP-BF531 processor

__ADSPBF532__ The ADSP-BF532 processor

__ADSPBF533__ The ADSP-BF533 processor

...

services.h file

-

-

The services.h file contains the full and complete list of processor vari­ants that are supported.

L

Device Drivers and System Services Manual for Blackfin Processors 1-11

Note: Although the API of the System Services does not change
between processor variants, the internals of the System Services dif
fer depending on the specific processor variant and processor
revision number being targeted. For example, the number of DMA
channels for the ADSP-BF533 differs from the number of DMA
channels for the ADSP-BF561. Further, a workaround within the
services for revision
sion x.y of that same processor. These differences are accounted for
in the System Service Library module. See

tory and File Structure” for more information.

x.y of a processor may not be needed for revi-

“System Services Direc-

-

System Services Overview

Linking in the System Services Library

All object code for the System Services is included in the System Services
library file. This file is found in the

blackfin/lib directory. In this direc-

tory is a System Services library file for each processor variant and
processor revision that is supported. The user should ensure that the
appropriate library is included in the list of object files for the linker. All
System Service Library files are of the form

libsslxxx_yyyzz.dlb where:

• xxx represents the processor variant - This is typically a 3-digit
number identifying the processor variant, such as 532 for the
ADSP-BF532, 534 for the ADSP-BF534, and so on.

• _yyy represents the operating environment - This suffix represents
the operating environment being targeted such as
VDK-based systems,

linux for Linux-based systems, and so on.

vdk for

Libraries built for standalone, specifically non-RTOS environ­ments, do not include the _yyy suffix.

• zz represents any special conditions for the library. The following
combinations are used:

• d - The library contains all debug information for the file.

• y - The library is built to avoid all known anomalies for all
revisions of silicon.

• dy - The library contains all debug information for the file
and is built to avoid all known anomalies for all revisions of
silicon.

• blank - A library without any additional suffix does not
include debug information and does not contain
workarounds to any anomalies.

Located within the blackfin/lib directory are subdirectories for
individual silicon revisions. The libraries in these subdirectories are
built for specific silicon revisions of the Blackfin processors.

1-12 Device Drivers and System Services Manual for Blackfin Processors

Introduction

Only a single System Services Library file should be included for the linker
to process. Application developers should choose the correct library based
on the processor variant, operating environment, and processor revision
number for their system.

For example, an application developer who wants a debug version of the
System Services Library and is targeting silicon revision 0.2 of the
ADSP-BF532 without any RTOS should link with the
file from the
example, the application developer who wants a release version of the Sys
tem Services Library that will run on any revision of ADSP-BF532 silicon
and is using the VDK, should link with the libss1532_vdky.dlb file from
the

blackfin/lib directory.

blackfin/lib/bf532_rev_0.2 subdirectory. As another

libss1532_d.dlb

-

L

Rebuilding the System Services Library

Under normal situations, there is no need to rebuild the System Services
Library. However, to accommodate unforeseen circumstances and provide
the user the ability to tailor the System Services to their particular needs,
all source code and include files necessary to rebuild the System Services
Library are provided. In addition, VisualDSP++ project files are included
for application developers using the VisualDSP++ development toolset.

It is strongly recommended that developers use the debug versions
of the System Services Library during development as built-in
error-checking code within the library can save countless hours of
development time.

Device Drivers and System Services Manual for Blackfin Processors 1-13

System Services Overview

All code for the System Services Library is located in the following
directories:

• blackfin/lib - This directory contains the Analog Devices built
versions of the System Service library files (

*.dlb).

• 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 black-

fin/include/services and blackfin/lib/src/services.

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. See the _si_revision switch in the compiler for
more information.

1-14 Device Drivers and System Services Manual for Blackfin Processors

Introduction

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).

Examples

The System Services distribution includes many examples that illustrate
how to use the System Services. Please refer to these examples for addi
tional information on how to use the System Services effectively.

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 Devices processors. It has also been designed
to provide a simple and efficient mechanism for the creation of new device
drivers.

Device Drivers and System Services Manual for Blackfin Processors 1-15

Device Driver Overview

Application Interface

The Device Driver Model provides a consistent, simple and familiar
Application Programming Interface (API) for device drivers. All devices
drivers that conform to the model use the same simple interface into the
driver.

Most devices either receive and/or transmit data, sometimes transforming
the data in the process. This data is encapsulated in a buffer. The buffer
may contain small bits of data, such as for a UART-type device that pro
cesses one character at a time, or large pieces of data, such as a video
device that processes NTSC frames of approximately 1MB in size. Appli
cations typically provide the buffers to the device, though it is possible for
devices to pass buffers from one device to another without any application
involvement.

The actual API into a model-compliant driver consists of the following
basic functions:

-

-

• adi_dev_Open() - Opens a device for use.

• adi_dev_Close() - Closes down a device.

• adi_dev_Read() - Provides a device with buffers for inbound data.

• 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.

1-16 Device Drivers and System Services Manual for Blackfin Processors

-

Introduction

Device Driver Architecture

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 applica
tion until the operation has completed. In asynchronous mode, the API
function returns immediately to the application, while the data is moved
in the background. It would be wasteful to force each and every device
driver (or more accurately, each and every Physical Driver) to provide
logic that operates both synchronously and asynchronously. The Device
Manager provides this functionality, relieving each Physical Driver from
re-implementing this capability.

-

The Device Manager also provides the API to the application for each
device driver. This ensures that the application has the same consistent
interface regardless of the peculiarities of each device.

While there is one and only one Device Manager exists in a system, there
can be any number of Physical Drivers in a system. A Physical Driver is
that component of a device driver that accesses and controls the physical
device. The Physical Driver is responsible for all the “bit banging” and
control and status register manipulations of the physical device. All device
specific information is contained and isolated in the Physical Driver.

Device Drivers and System Services Manual for Blackfin Processors 1-17

Device Driver Overview

This architecture is illustrated in Figure 1-2:

APPLICATION

RTOS (OPTIONAL)

DEVICE
DRIVER

COMPONENTS

DEVICE MANAGER

PHYSICAL

DRIVER

PHYSICAL

DRIVER

PHYSICAL

DRIVER

SYSTEM SERVICES

Figure 1-2. Device Manager Architecture

Interaction with System Services

As shown in Figure 1-2, the Device Driver Model leverages the capabili­ties of the System Services. Each software component in the system,
whether it is the application, RTOS (if present), the Device Manager, or
each Physical Driver can access and call into the System Services API.

The benefits of using this approach are enormous. In addition to the code
size and data memory savings, this approach allows each software compo

-

nent access to the resources of the system and processor in a cooperative

1-18 Device Drivers and System Services Manual for Blackfin Processors

Introduction

manner. Further, the amount of development effort for Physical Drivers is
substantially reduced as each driver does not have to re-implement any of
the functionality provided by the Device Manager or System Services.

Initialization

Prior to accessing any individual driver, the Device Manager must first be
initialized. The initialization function,
application to setup and initialize the Device Manager.

Though the Device Driver Model is dependent upon System Services, the
initialization function of the Device Manager does not rely on any of the
System Services. As such the current revision of the Device Manager can
be initialized either before or after the System Services initialization.

However, future versions of the Device Manager initialization function
may require some of the System Services capabilities. As such, it is good
practice to initialize the required System Services prior to initializing the
Device Manager. Refer to the
mation on the initialization of the System Services.

“Initialization” on page 1-7 for more infor-

adi_dev_Init(), is called by the

Termination

The API of the Device Driver Model includes a termination function that
may be called by the application if the device drivers are no longer
required. The termination function, adi_dev_Terminate(), is called to
free up the resources used by the Device Manager and any open Physical
Drivers. Many embedded systems run in an endless operating loop and
never call the termination function of the Device Manager. Applications
that operate in endless loops can save program memory by not calling the
terminate function.

Device Drivers and System Services Manual for Blackfin Processors 1-19

Device Driver Overview

As part of the termination function processing, the Device Manager closes
all open Physical Drivers. The Physical Drivers are closed in an abrupt
manner. If a more graceful shutdown is needed, the application may prefer
to close any open Physical Drivers first, and then call the termination
function.

Note that because of the reliance on the System Services, the termination
function of the Device Manager should be called prior to any termination
functions of the System Services. This ensures that the System Services can
be called by the Device Manager and/or Physical Drivers as part of their
shutdown procedure.

After the Device Manager has been terminated, it must be re-initialized
before any of its functionality can be accessed again.

Device Driver Directory and File Structure

All files for the Device Driver Model are contained within the blackfin
directory tree. In VisualDSP++ installations this is the same directory as
the one used for storing the core development tools. Other development
toolsets may use other directory names for their toolkits, but the Device
Driver files can always be found within the

blackfin directory tree.

To use the device drivers, applications need only use some include files in
their source code, and link with a Device Driver Library and a System Ser
vices Library module.

Accessing the Device Driver API

Applications using the Device Driver Model should include the black-

fin/include/services and blackfin/include/drivers directories in the

compilers/assemblers pre-processor search path. User source files accessing
the Device Manager API should include the files

dev.h

, in order, located in the blackfin/include/services and black-

services.h and adi_

1-20 Device Drivers and System Services Manual for Blackfin Processors

-

Introduction

fin/include/drivers directories, respectively. In addition, the user’s

source file should use the include file of the Physical Driver that will be
accessed.

For example, user code that is accessing the Analog Devices Parallel
Peripheral Interface (PPI) driver would include the following lines in their
source file (in order):

#include "services.h” // system services
#include "adi_dev.h” // device manager
#include "adi_ppi.h” // ppi physical driver

The Device Driver API and functionality is uniform and consistent across
all Blackfin processors, including all single and multi-core devices. Appli­cation software does not change regardless of which Blackfin processor is
being targeted. For example application software running on a single core
ADSP-BF533 processor can operate unchanged on a multi core
ADSP-BF561 processor.

In order to provide this consistent API to the application, the System Ser­vices, Device Manager and Physical Drivers need to be aware of the
specific processor variant being targeted. The user should ensure that the
processor definition macro for the processor variant being targeted is
defined when including the System Services,

services.h, Device Man-

ager, adi_dev.h, and physical driver include files.

The VisualDSP++ toolset automatically sets the processor definition
macro when building projects. Application developers using the Visu

­alDSP++ toolset need do nothing further to ensure the processor
definition macro is defined.

Application developers using other toolsets should, however, ensure the
processor definition macro is appropriately defined. The
enumerates the specific processor variants that are supported. These pro

services.h file

-

cessor variants include:

Device Drivers and System Services Manual for Blackfin Processors 1-21

Device Driver Overview

__ADSPBF531__ The ADSP-BF531 processor

__ADSPBF532__ The ADSP-BF532 processor

__ADSPBF533__ The ADSP-BF533 processor

...

The services.h file contains the full and complete list of processor vari­ants that are supported by the System Services. The adi_dev.h file
contains the list of processor families that are supported by the Device
Driver Model.

Linking in the Device Driver Library

All object code for the Device Manager and Analog Devices-supplied
Physical Drivers is included in the Device Driver library file. This file is
found in the

blackfin/lib directory. In this directory is a Device Driver

library file for each and every processor variant that are supported. The
user should ensure that the appropriate library is included in the list of
object files for the linker. The Device Driver Library file is of the form

libdrvxxxzz.dlb where:

• xxx represents the processor variant - This is typically a 3-digit

number identifying the processor variant such as 532 for the
ADSP-BF532, 534 for the ADSP-BF534, and so on.

• zz represents any special conditions for the library. The following

combinations are used:

• d - the library contains all debug information for the file.

• y - The library is build to avoid all known anomalies for all
revisions of silicon.

1-22 Device Drivers and System Services Manual for Blackfin Processors

Introduction

• dy - The library contains all debug information for the file
and is built to avoid all known anomalies for all revisions of
silicon.

• blank - A library without an additional suffix does not
include debug information and does not contain
workarounds to any anomalies.

Located within the blackfin/library directory are subdirectories for
individual silicon revisions. The libraries in these subdirectories are built
for specific silicon revisions of the processors.

Only a single Device Driver Library file should be included for the linker
to process. The application developer should choose the correct library
based on the processor variant for their system.

For example, an application developer who wants a debug version of the
Device Driver Library and is targeting silicon revision 0.2 of the
ADSP-BF532 should link with the

fin/lib/bf532_rev_0.2 subdirectory. As another example, the application

developer who wants a release version of the Device Driver Library that
will run on any revision of ADSP-BF532 silicon should link with the

libdrv532y.dlb file from the blackfin/lib directory.

libdrv532d.dlb file from the black-

L

Rebuilding the Device Driver Library

Under normal situations, there is no need to rebuild the Device Driver
Library. However, to accommodate unforeseen circumstances and provide
the user with the ability to tailor the implementation to their particular
needs, all source code and include files necessary to rebuild the Device

Device Drivers and System Services Manual for Blackfin Processors 1-23

It is strongly recommended that developers use the debug versions
of the Device Driver Library during development, because built-in
error-checking code within the library can save countless hours of
development time.

Device Driver Overview

Driver Library are provided. In addition, VisualDSP++ project files are
included for application developers using the VisualDSP++ development
toolset.

All code for the Device Driver Library is located in the following
directories:

• blackfin/lib - This directory contains the Analog Devices built
versions of the Device Driver library files (

*.dlb).

• blackfin/lib/src/drivers - This directory contains all the source
code files and non-API include files for the Device Manager and
Analog Devices provided Physical Drivers. Also in this directory
are the VisualDSP++ project files that can be used to rebuild the
libraries.

• blackfin/include/drivers - This directory contains the Device
Manager API include file and the include files for all Analog
Devices provided Physical Drivers.

VisualDSP++ users can rebuild the Device Driver Library by using the

build command after opening the appropriate VisualDSP++ project file.

To rebuild the libraries using other development toolsets, the following
steps should be performed:

1. Set the pre-processor include path to include black-

fin/include/drivers and blackfin/lib/src/drivers.

2. Define the processor variant according to the definitions in the

services.h file.

1-24 Device Drivers and System Services Manual for Blackfin Processors

Introduction

3. Define the silicon revision macro, __SILICON_REVISION__, to the
proper value. See the

-si-revision switch in the compiler for

more information.

4. Compile/assemble all files in the directory

blackfin/lib/src/drivers.

• Link the appropriate compiled/assembled objects including all
object files into a library.

Examples

The Device Driver distribution includes examples that illustrate how to
use the Device Drivers. Please refer to these examples for additional infor
mation on how to use the Device Drivers effectively.

-

Device Drivers and System Services Manual for Blackfin Processors 1-25

Device Driver Overview

1-26 Device Drivers and System Services Manual for Blackfin Processors

2 INTERRUPT MANAGER

This chapter describes the Interrupt Manager that controls and manages
the interrupt and event operations of the Blackfin processor.

This chapter contains:

• “Introduction” on page 2-2

• “Examples” on page 2-15

• “Interrupt Manager API Reference” on page 2-17

Device Drivers and System Services Manual for Blackfin Processors 2-1

Introduction

Introduction

The Blackfin processor employs a two-tiered mechanism for controlling
interrupts and events. System level interrupts are controlled by the System
Interrupt Controller (SIC). All peripheral interrupt signals are routed
through the System Interrupt Controller and then, depending on the set
tings of the System Interrupt Controller, routed to the Core Event
Controller (CEC). The Core Event Controller processes these events and,
depending on the settings of the Core Event Controller, vectors the pro
cessor to handle the events.

The Interrupt Manager provides functions that allow the application to
control every aspect of both the System Interrupt Controller and the Core
Event Controller. It does this so that events and interrupts are handled
and processed in an efficient, yet cooperative, manner.

The Blackfin processor provides 16 levels of interrupt and events. These
levels, called Interrupt Vector Groups (IVG), are numbered from 0 to 15,
with the lowest number having the highest the priority. Some IVG levels
are dedicated to certain events, such as emulation, reset, Non-Maskable
Interrupt (NMI) and so on. Other IVG levels, specifically levels 7 through
15, are considered general purpose events and are typically used for system
level (peripheral) interrupts or software interrupts. All IVG processing is
performed in the CEC. When a specific IVG is triggered, assuming the
event is enabled, the CEC looks up the appropriate entry in the Event
Vector Table, and vectors execution to the address in the table where the
event is processed.

-

-

All system or peripheral interrupts are first routed through the SIC.
Assuming the SIC has been so programmed, peripheral interrupts are then
routed to the CEC for processing. The SIC provides a rich set of function
ality for the processing and handling of peripheral interrupts. In addition
to allowing/disallowing peripheral interrupts to be routed to the CEC, the

2-2 Device Drivers and System Services Manual for Blackfin Processors

-

Interrupt Manager

SIC allows peripheral interrupts to be mapped to any of the CEC’s general
purpose IVG levels, and controls whether or not these interrupts wake the
processor from an idled operating mode.

In systems employing Blackfin processors, there are often more potential
interrupt sources than there are IVG levels. As stated above, some events,
such as NMI, map one to one to an IVG level. Others, typically infre
quent interrupts such as peripheral error interrupts are often “ganged” in a
single IVG level.

The Interrupt Manager allows the application to execute complete control
over how interrupts are handled, whether they are masked or unmasked,
mapped one to one or ganged together, whether the processor should be
awakened to service an interrupt and so on. The Interrupt Manager also
allows the creation of interrupt handler chains. An interrupt handler is a
C-callable function that is provided by the application to process an inter
rupt. Through the Interrupt Manager, the application can hook in any
number of interrupt handlers for any IVG level. In the case where multi
ple events are ganged to a single IVG level, this allows each handler to be
designed independently from any other and allows the application to pro
cess these interrupts in a straightforward manner.

-

-

-

-

Further, the Interrupt Manager only processes those IVG levels and sys­tem interrupts that the application directs the Interrupt Manager to
control. This allows the application developer to have complete unfettered
access to any IVG level or system interrupt, if they want manual control of
interrupts.

Multi-core Blackfin processors extend on this by including one System
Interrupt Controller and one Core Event Controller for each core. This
provides maximum flexibility by allowing application developers to decide
how to map interrupts to individual cores, multiple cores and so on.
When using multi-core Blackfin processors, typically one Interrupt Man
ager for each core is used. Because there is no reason to provide multiple

Device Drivers and System Services Manual for Blackfin Processors 2-3

-

Initialization

Interrupt Managers on single core devices, this service is not supported.
Application developers should not attempt to instantiate more than one
Interrupt Manager per core.

Following the convention of all the System Services, the Interrupt Man­ager uses a unique and unambiguous naming convention to guard against
conflicts. All enumeration values, typedefs and macros use the
prefix, while all functions within the Interrupt Manager use the

ADI_INT_

adi_int_

prefix.

All Interrupt Manager API functions return the ADI_INT_RESULT return
code. See the

adi_int.h file for the list of return codes. Like all System

Services, the return code that signals successful completion, ADI_INT_

RESULT_SUCCESS

for the Interrupt Manager, is defined to be 0, allowing
applications to quickly and easily determine if any errors occurred in
processing.

Initialization

In order to use the functionality of the Interrupt Manager, the Interrupt
Manager must first be initialized. The initialization function of the Inter
rupt Manager is called adi_int_Init. The application passes to the
initialization function memory that the Interrupt Manager can use during
its lifetime.

The amount of memory that should be provided depends on the number
of secondary handlers that are to be used by the application. When using
interrupt handler chaining, the Interrupt Manager considers the first
interrupt handler that is hooked into an IVG level to be the primary inter
rupt handler. Any additional interrupt handlers that hooked into that
same IVG level are considered secondary handlers. Without any addi
tional memory from the application, the Interrupt Manager can support
one primary interrupt handler for each IVG level. If the application never
has more than one interrupt handler on each IVG level, in other words
only the primary interrupt handler and no secondary handlers are present,

2-4 Device Drivers and System Services Manual for Blackfin Processors

-

-

-

Interrupt Manager

then the application does not need to provide memory to the Interrupt
Manager’s initialization function. If however, the application will be
hooking in secondary interrupt handlers, the application needs to provide
additional memory to support the secondary handlers. The macro

INT_SECONDARY_MEMORY

is defined to be the amount of memory, in bytes,

ADI_

that is required to support a single secondary handler. Therefore, the
application should provide ‘n’ times

ADI_INT_SECONDARY_MEMORY to the

initialization function, where ‘n’ is the number of secondary handlers that
are to be supported.

Another parameter passed to the initialization function is the parameter
that the Interrupt Manager passes to the adi_int_EnterCriticalRegion()
function. This value is dependent upon the operating environment of the
application. See the

adi_int_EnterCriticalRegion function below for

more information.

When called, the initialization function initializes its internal data struc­tures and returns. No changes are made to either the CEC or SIC during
initialization. After initialization, any of the other Interrupt Manager API
functions may be called.

Termination

When the functionality of the Interrupt Manager is no longer required,
the application can call the termination function of the Interrupt Man
ager, adi_int_Term(). Many applications operate in an endless loop and
never call the termination function.

When called, the termination function unhooks all interrupt handlers,
masking off (disabling) all interrupts that the Interrupt Manager was con­trolling. After calling the termination function, any memory provided to
the initialization function may be re-used by the application. No other
Interrupt Manager functions can be called after termination. If Interrupt

Device Drivers and System Services Manual for Blackfin Processors 2-5

-

Core Event Controller Functions

Manager services are required after the termination function is called, the
application must re-initialize Interrupt Manager services by calling the

adi_pwr_Init function.

Core Event Controller Functions

Only two functions are necessary to provide complete control over the
Core Event Controller.

adi_int_CECHook()

The adi_int_CECHook() function is used to hook an interrupt handler
into the handler chain for an IVG level. When called, the application
passes in the IVG number that is to be handled, the address of the handler
function, a parameter that the Interrupt Manager automatically passes
back to the interrupt handler when the interrupt handler is invoked, and a
flag indicating whether or not interrupt nesting should be enabled for this
IVG level.

The handler function itself is a simple C-callable function that conforms
to the

ADI_INT_HANDLER_FN typedef. The interrupt handler is not an

Interrupt Service Routine (ISR) but a standard C-callable function. When
the IVG level triggers it, the Interrupt Manager calls the interrupt handler
to process the event. The Interrupt Manager passes the client argument
that was passed to the Interrupt Manager via the

adi_int_CECHook() func-

tion to the interrupt handler. The interrupt handler takes whatever action
is necessary to process the interrupt, then returns with either the

RESULT_PROCESSED

or ADI_INT_RESULT_NOT_PROCESSED return code.

ADI_INT_

Interrupt handlers should be written in such a way so as to interrogate the
system quickly to determine if the event that triggered the interrupt
should be processed by the interrupt handler. If the event that caused the
interrupt is not the event the interrupt handler was expecting, the inter

-

rupt handler should immediately return with the ADI_INT_RESULT_NOT_

2-6 Device Drivers and System Services Manual for Blackfin Processors

Interrupt Manager

PROCESSED return code. If the interrupt handler returns the ADI_INT_
RESULT_NOT_PROCESSED

return code, then the Interrupt Manager automat­ically invokes the next interrupt handler, if any, that is hooked into the
same IVG level. If the event that caused the interrupt is expected by the
interrupt handler, the interrupt handler performs whatever processing is
necessary and then returns the
an interrupt handler returns the

ADI_INT_RESULT_PROCESSED return code. If

ADI_INT_RESULT_PROCESSED return code,

the Interrupt Manager does not invoke any other interrupt handlers that
may be hooked into that IVG chain.

The nesting flag parameter is of significance only when the first interrupt
handler is hooked into an IVG chain. The first interrupt handler that
hooks into an IVG chain is called the primary handler. Any additional
handlers that are hooked into that same IVG chain are called secondary
handlers. When the primary handler is hooked into the chain, the Inter

­rupt Manager loads an ISR into the appropriate entry of the Event Vector
Table. If the nesting flag is set, the ISR that the Interrupt Manager loads is
one that supports interrupt nesting. If the nesting flag is clear, then the
ISR that the Interrupt Manager loads is one that does not support inter

­rupt nesting. When secondary handlers are hooked into an IVG chain, the
nesting flag is ignored.

Lastly, the adi_int_CECHook() function unmasks the appropriate bit in
the CEC’s IMASK register, thereby enabling the interrupt to be processed.

In most applications, users take great care to optimize the processing that
occurs for the highest frequency and highest urgency interrupts. Typically,
the highest frequency or highest urgency interrupts are assigned their own
IVG level, while less frequent or lower urgency interrupts, such as error
processing, are ganged together on a single IVG level.

The Interrupt Manager continues that thinking and has been optimized to
allow extremely efficient processing for primary interrupt handlers.
Though still efficient, secondary handlers are called after the primary han
dler. Secondary handlers are hooked into the IVG chain in a stacked or
Last In First Out (LIFO) fashion. This means that when an event is trig

-

Device Drivers and System Services Manual for Blackfin Processors 2-7

-

Core Event Controller Functions

gered, after calling the primary handler (and assuming the primary
handler did not return the

ADI_INT_RESULT_PROCESSED return code), the

Interrupt Manager calls the last secondary handler that was hooked, fol
lowed by the second to last installed handler, and so on.

To ensure optimal performance, the application developer should manage
which interrupt handlers are hooked as primaries and which are hooked as
secondary handlers.

adi_int_CECUnhook()

The adi_int_CECUnhook() function is used to unhook an interrupt han­dler from the interrupt handler chain for a particular IVG level. When
called, the application passes in the IVG number and the address of the
interrupt handler function that is to be unhooked from the chain.

The function removes the interrupt handler from the chain of handlers for
the given IVG level. If the primary handler is being removed, the last sec
ondary handler that was hooked becomes the new primary handler. If after
removing the given interrupt handler there are no interrupt handlers left
in the IVG chain, the
ate bit in the CEC’s IMASK register, thereby disabling the interrupt.

adi_int_CECUnhook() function masks the appropri-

-

-

Interrupt Handlers

Since the interrupt handlers registered with the Interrupt Manager are
invoked from within the built-in IVG interrupt service routine, and since
there may be several interrupts pending for the same IVG level, individual
interrupt handlers must not invoke the
Instead, they should return using the RTS return function. Interrupt han
dlers are in fact nothing more than typical C-callable subroutines.

2-8 Device Drivers and System Services Manual for Blackfin Processors

RTI instruction on completion.

-

Interrupt Manager

Each peripheral interrupt handler must, therefore, conform to the follow­ing template,

ADI_INT_HANDLER(mjk_SPORT_RX_handler)
{

... ... // user code

}

where the ADI_INT_HANDLER macro is defined as

#define ADI_INT_HANDLER(NAME) \
void (*NAME)(void *ClientArg)

System Interrupt Controller Functions

The following functions are provided to give the application complete
control over the System Interrupt Controller:

• adi_int_SICEnable() - Enables peripheral interrupts to be passed
to the CEC.

• adi_int_SICDisable() - Disables peripheral interrupts from being
passed to the CEC.

• adi_int_SICSetIVG() - Sets the IVG level to which a peripheral
interrupt is mapped.

• adi_int_SICGetIVG() - Detects the IVG level to which a peripheral
interrupt is mapped.

• adi_int_SICWakeup() - Establishes whether or not a peripheral
interrupt wakes up the processor from an idled state.

• adi_int_SICInterruptAsserted() - Detects whether or not a
peripheral interrupt is asserted.

Device Drivers and System Services Manual for Blackfin Processors 2-9

System Interrupt Controller Functions

All SIC functions take as a parameter an enumeration value that uniquely
identifies a peripheral interrupt. The enumeration

ID

identifies each possible peripheral interrupt source for the processor.

This enumeration is defined in the

adi_int.h file. Refer to the file for the

ADI_INT_PERIPHERAL_

complete list of values for each supported Blackfin processor.

adi_int_SICDisable()

The adi_int_SICDisable() function is used to disable a peripheral inter­rupt from being passed to the Core Event Controller. When called, this
function programs the appropriate SIC IMASK register to disable the
given peripheral interrupt.

adi_int_SICEnable()

The adi_int_SICEnable() function is used to enable a peripheral inter­rupt to be passed to the Core Event Controller. When called, this function
programs the appropriate SIC IMASK register to enable the given periph
eral interrupt.

-

adi_int_SICGetIVG()

The adi_int_SICGetIVG() function is used to detect the IVG level to
which a peripheral interrupt is mapped. In addition to the

PERIPHERAL_ID

parameter, this function is passed pointer-to-memory loca­tion information. The function interrogates the proper field of the
appropriate SIC Interrupt Assignment register and stores the IVG level (0
to 15) to which the given peripheral interrupt is mapped into the memory
location.

2-10 Device Drivers and System Services Manual for Blackfin Processors

ADI_INT_

Interrupt Manager

adi_int_SICInterruptAsserted()

The adi_int_SICInterruptAsserted() function is used to detect whether
or not the given peripheral interrupt is asserted. Though it can be called at
any time, it is intended that this function is called immediately by the
application’s interrupt handlers to determine if a given peripheral inter
rupt is being asserted, allowing the interrupt handler to determine if its
peripheral is asserting the interrupt.

Instead of using the usual ADI_INT_RESULT_SUCCESS return code, this func­tion returns the ADI_INT_RESULT_ASSERTED or ADI_INT_RESULT_NOT_

ASSERTED

return code upon a successful completion. If errors are detected
with the calling parameters, this function may return a different error
code.

adi_int_SICSetIVG()

-

The adi_int_SICSetIVG() function is used to set the IVG level to which a
peripheral interrupt is mapped. Upon powerup, the Blackfin processor
invokes a default mapping of peripheral interrupts to IVG level. This
function alters that mapping. In addition to the

ADI_INT_PERIPHERAL_ID

parameter, this function is passed the IVG level (0 to 15) to which the
peripheral interrupt should be mapped. The function modifies the proper
field within the appropriate SIC Interrupt Assignment register to the new
mapping.

adi_int_SICWakeup()

The adi_int_SICWakeup() function is used to enable or disable a periph­eral interrupt from waking up the core when the interrupt trigger and the
core are in an idled state. In addition to the
parameter, this function is passed a TRUE/FALSE flag. If the flag is
TRUE, the SIC Interrupt Wakeup register is programmed such that the
given peripheral interrupt wakes up the core when the interrupt is trig

Device Drivers and System Services Manual for Blackfin Processors 2-11

ADI_INT_PERIPHERAL_ID

-

Protecting Critical Regions

gered. If the flag is FALSE, the SIC Interrupt Wakeup register is
programmed such that the given peripheral interrupt does not wake up the
core when the interrupt is triggered.

Note that this function does not enable or disable interrupt processing.
Also note that it is possible to configure the SIC so that a peripheral inter
rupt wakes up the core from an idled state but does not process the
interrupt. This may or may not be the intended operation.

Protecting Critical Regions

In embedded systems it is often necessary to protect a critical region of
code while it is being executed. This is often necessary while one logical
programming sequence is updating or modifying a piece of data. In these
cases, another logical programming sequence, such as interrupt processing
in one system, or different thread in an RTOS based system, is prevented
from interfering while the critical data is being updated.

-

To that end, the Interrupt Manager provides two functions that can be
used to bracket a critical region of code. These functions are adi_int_

EnterCriticalRegion()

cation calls the adi_int_EnterCriticalRegion() function at the
beginning of the critical section of code, and then calls the adi_int_Exit-

CriticalRegion() function at the end of the critical section. These

functions should always be used in pairs.

The actual implementation of these functions varies from operating envi­ronment to operating environment. For example in a standalone system,
in systems without any RTOS, what actually happens in these functions
may be different than the version of these functions for an RTOS based
system. The principle and usage however, are always the same regardless of
implementation. In this way, application code always operates the same
way, and does not have to change regardless of the operating environment.

2-12 Device Drivers and System Services Manual for Blackfin Processors

and adi_int_ExitCriticalRegion(). The appli-

Interrupt Manager

The adi_int_EnterCriticalRegion() function is passed an argument of

void * and returns an argument of type void *. The value that is

type
returned from the
be passed to the corresponding

adi_int_EnterCriticalRegion() function must always

adi_int_ExitCriticalRegion() function.

For example, examine the following code sequence:

…
Value = adi_int_EnterCriticalRegion(pArg);
… // critical section of code
adi_int_ExitCriticalRegion(Value);
…

The value that is returned from the adi_int_EnterCriticalRegion()
function must be passed to the corresponding

gion() function. While nesting of calls to these functions is allowed, the

adi_int_ExitCriticalRe-

application developer minimizes the use of these functions to only those
critical sections of code, and realize that in all likelihood the processor is
being placed in some altered state. This could affect the performance of
the system, while in the critical regions. For example, it could be that
interrupts are disabled in the critical region. The application developer
typically does not want to have interrupts disabled for long periods of
time. These functions should be used sparingly and judiciously.

Nesting of these calls is allowed. For example consider the following code
sequence that makes a call to the function

Foo() while in a critical section

of code. The function Foo() also has a critical region of code.

…
Value = adi_int_EnterCriticalRegion(pArg);
… // critical section of code
Foo(); // call to Foo()
adi_int_ExitCriticalRegion(Value);
…

void Foo(void) {
void *Value;
…
Value = adi_int_EnterCriticalRegion(pArg);

Device Drivers and System Services Manual for Blackfin Processors 2-13

Modifying IMASK

… // critical section of code
adi_int_ExitCriticalRegion(Value);
…
}

This practice is allowed, however the application developer is cautioned
that overuse of these functions can affect system performance.

The pArg value that is passed into the adi_int_EnterCriticalRegion()
function is dependent upon the actual implementation for the given oper
ating environment. In some operating environments the value is not used
and can be NULL. The user should check the source file for the specific
operating environment,

vices directory where xxx is the operating environment, for more

information on the

adi_int_xxx.c in the blackfin/lib/src/ser-

pArg parameter.

-

L

All system services and device drivers use these functions exclu­sively to protect critical regions of code. Application software
should also use these functions exclusively to protect critical
regions of code within the application.

Modifying IMASK

Though applications rarely need to have the processor’s IMASK register
value modified, the Interrupt Manager itself modifies the IMASK register
value to control the CEC properly. In some RTOS-based operating envi
ronments, the RTOS tightly controls the IMASK register and provides
functions that allow the manipulation of IMASK.

In order to ensure compatibility across all operating environments, the
Interrupt Manager provides functions that allow bits within the IMASK
register to be set or cleared. Depending on the operating environment,
these function may modify the IMASK value directly, or use the RTOS
provided IMASK manipulation functions. Regardless of how the IMASK
value is changed, the Interrupt Manager API provides a uniform and con
sistent mechanism for this.

-

-

2-14 Device Drivers and System Services Manual for Blackfin Processors

Interrupt Manager

Two operating environment implementation dependent functions are
provided to set and clear bits in the

adi_int_SetIMASKBits() and adi_int_ClearIMASKBits. These functions

take as a parameter a value that corresponds to the
processor being targeted. When the
called, the function sets to 1 those bits in the

IMASK register. These functions are

IMASK register of the

adi_int_SetIMASKBits() function is

IMASK register that have a

one in the corresponding bit position of the value passed in. When the

adi_int_ClearIMASKBits() function is called, the function clears those

bits (to 0) in the

IMASK register that have a 1 in the corresponding bit posi-

tion of the value passed in.

Consider the following example code. Assume that IMASK is a 32-bit
value and contains 0x00000000 upon entry into the code:

…
… // IMASK = 0x00000000
ReturnCode = adi_int_SetIMASKBits(0x00000003);
… // IMASK now equals 0x00000003
ReturnCode = adi_int_ClearIMASKBits(0x00000001);
… // IMASK now equals 0x00000002
ReturnCode = adi_int_ClearIMASKBits(0x00000002);
… // IMASK now equals 0x00000000

While it is very unlikely that the application ever needs to control individ­ual IMASK bit values, the Interrupt Manager uses these functions to control
the CEC.

Examples

Examples demonstrating use of the Interrupt Manager can be found in the

blackfin/EZ-Kits subdirectories.

Device Drivers and System Services Manual for Blackfin Processors 2-15

File Structure

File Structure

The API for the Interrupt Manager is defined in the file adi_int.h. This
file is located in the
matically included by the services.h file in that same directory. Only the

services.h file should be included in the application code.

Applications should link with one and only one of the System Services
library files. These files are located in the
appropriate section in the “Introduction” on page 6-1 in DMA Manager
for more information on selecting the proper library file.

For convenience, all source code for the Interrupt Manager is located in
the blackfin/lib/src/services directory. All operating environment
dependent code is located in the file a
ating environment being targeted. These files should never be linked into
an application, as the appropriate System Services Library file contains all
required object code.

blackfin/include/services subdirectory and is auto-

blackfin/lib directory. See the

di_int_xxx.c where xxx is the oper-

2-16 Device Drivers and System Services Manual for Blackfin Processors

Interrupt Manager

Interrupt Manager API Reference

This section provides descriptions of the Interrupt Manager module’s
Application Programming Interface (API) functions.

Notation Conventions

The reference pages for the API functions use the following format:

Name and purpose of the function

Description – Function specification

Prototype – Required header file and functional prototype

Arguments – Description of function arguments

Return Value – Description of function return values

Device Drivers and System Services Manual for Blackfin Processors 2-17

Interrupt Manager API Reference

adi_int_Init

Description

This function sets aside and initializes memory for the Interrupt Manager.
It also initializes other tables and vectors within the Interrupt Manager.
This function should only be called once per core. Separate memory areas
should be assigned for each core.

Prototype

ADI_INT_RESULT adi_int_CECInit(
void *pMemory,
const size_t MemorySize,
u32 *pMaxEntries,
void *pEnterCriticalArg

);

Arguments

*pMemory This is the pointer to an area of memory to be used by the

Interrupt Manager.

MemorySize This is the size, in bytes, of memory being supplied for the Inter-

rupt Manager.

*pMaxEntries On return, this argument contains the number of secondary han-

dler entries that the Interrupt Manager can support given the
memory supplied.

*pEnterCriticalArg Parameter passed to the adi_int_EnterCriticalRegion.

Return Value

Return values include:

ADI_INT_RESULT_SUCCESS Successfully initialized

2-18 Device Drivers and System Services Manual for Blackfin Processors

Interrupt Manager

adi_int_Terminate

Description

This function closes down the Interrupt Manager. All memory used by the
Interrupt Manager is freed up, all handlers are unhooked, and all Inter
rupt Vector Groups that were enabled and controlled by the Interrupt
Manager are disabled.

-

L

Prototype

ADI_INT_RESULT adi_int_Terminate(void);

Arguments

none

Return Value

The function returns ADI_INT_RESULT_SUCCESS if successful. Any other
value indicates an error.

Note that the adi_int_Terminate function does not alter the Sys­tem Interrupt Controller settings. Should changes to the SIC be
required, the application should make the appropriate calls into the
relevant SIC control functions before calling

Terminate()

.

adi_int_

Device Drivers and System Services Manual for Blackfin Processors 2-19

Interrupt Manager API Reference

adi_int_CECHook

Description

This function instructs the Interrupt Manager to hook (insert) the given
interrupt handler into the interrupt handler chain for the given IVG.

On a return from this call, the core event controller is programmed such
that the given IVG is unmasked (enabled) and the system is properly con
figured to service the interrupt via the Interrupt Manager’s built-in ISRs.
The ISRs then invoke the interrupt handler supplied by the caller.
Depending on the state of the

NestingFlag parameter, the Interrupt Man-

ager installs its built-in interrupt service routine with interrupt nesting,
either enabled or disabled.

On the first call for a given IVG level, the Interrupt Manager registers its
built-in IVG interrupt service routine against that level and establishes the
supplied interrupt handler as the primary interrupt handler for the given
IVG level. Subsequent calls to

adi_int_CECHook for the same IVG level

create a chain of secondary interrupt handlers for the IVG level. When the
interrupt for the IVG level is triggered, the primary interrupt handler is
first called, and then if present, each secondary interrupt handler is subse
quently called.

-

-

The ClientArg parameter provided in the adi_int_CECHook function is
passed to the interrupt handler as an argument when the interrupt handler
is called in response to interrupt generation.

Prototype

ADI_INT_RESULT adi_int_CECHook(
u32 IVG,
ADI_INT_HANDLER_FN Handler,
void *ClientArg,
u32 NestingFlag
);

2-20 Device Drivers and System Services Manual for Blackfin Processors

Interrupt Manager

Arguments

IVG This is the interrupt vector group number that is being

addressed.

Handler The client’s interrupt handler to be inserted into the

chain for the given IVG.

ClientArg A void * value that is passed to the interrupt handler.

NestingFlag This is the argument that selects whether nesting of inter-

rupts is allowed or disallowed for the IVG
(TRUE/FALSE).

Return Value

Return values include:

ADI_INT_RESULT_SUCCESS The interrupt handler was successfully hooked into the

chain.

ADI_INT_RESULT_NO_MEMORY Insufficient memory is available to insert the handler

into the chain.

ADI_INT_RESULT_INVALID_IVG The IVG level is invalid.

Device Drivers and System Services Manual for Blackfin Processors 2-21

Interrupt Manager API Reference

adi_int_CECUnhook

Description

This function instructs the Interrupt Manager to unhook (remove) the
given interrupt handler from the interrupt handler chain for the given
IVG.

If the given interrupt handler is the only interrupt handler in the chain,
the CEC is programmed to disable (mask) the given IVG and the Inter
rupt Manager built-in interrupt service routine is removed from the IVG
entry within Event Vector Table.

If the chain for the given IVG contains multiple interrupt handlers, the
given interrupt handler is simply purged from the chain. If the primary
interrupt handler is removed and there are secondary interrupt handlers in
the chain are present, one of the secondary interrupt handlers becomes the
primary interrupt handler.

-

Prototype

ADI_INT_RESULT adi_int_CECUnhook(
u32 IVG,
ADI_INT_HANDLER_FN Handler,
);

Arguments

IVG The interrupt vector group number that is being

addressed.

Handler The client’s interrupt handler to be removed from the

chain for the given IVG.

Return Value

Return values include:

2-22 Device Drivers and System Services Manual for Blackfin Processors

Interrupt Manager

ADI_INT_RESULT_SUCCESS The interrupt handler was successfully unhooked from

the chain.

ADI_INT_RESULT_INVALID_IVG The IVG level is invalid.

Device Drivers and System Services Manual for Blackfin Processors 2-23

Interrupt Manager API Reference

adi_int_ClearIMaskBits

Description

This function is used by the Interrupt Manager to clear bits in the IMASK
register. Though it can also be called by the application, the application
should not attempt to modify bits in the

IMASK register that represent

interrupt vector groups that are under the control of the Interrupt
Manager.

The implementation of this function depends upon the operating environ­ment. In the standalone version of the service, this function detects if the
processor is within a protected region of code (see the adi_int_Enter-

CriticalRegion and adi_int_ExitCriticalRegion functions). If it is, the

saved value of IMASK is updated accordingly and the current “live” IMASK
value is left unchanged. When the outermost adi_int_ExitCriticalRe-

gion 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 pro
tected 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 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
‘1’ 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

Device Drivers and System Services Manual for Blackfin Processors 2-25

Interrupt Manager API Reference

adi_int_EnterCriticalRegion

Description

This function creates a condition that protects a critical region of code.
The companion function,

adi_int_ExitCriticalRegion, removes the

condition. These functions should be used to bracket a section of code
that needs protection from other processing. These functions should be
used in pairs, sparingly and only when critical regions of code need
protecting.

The return value from this function should be passed to the corresponding

adi_int_ExitCriticalRegion function.

The actual condition that is created is dependent upon the operating envi­ronment. In the standalone version of the service, this function effectively
disables interrupts, saving the current value of IMASK to a temporary loca­tion. The adi_int_ExitCriticalRegion function restores the original

IMASK value. These functions employ a usage counter so that they can be

nested. When nested, the IMASK value is altered only at the outermost lev­els. In the standalone version, the pArg parameter to the adi_int_

EnterCriticalRegion

is meaningless.

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 and from processor to pro

­cessor. Application software does not need to change when moving to a
different operating environment or moving from one Blackfin derivative
to another.

2-26 Device Drivers and System Services Manual for Blackfin Processors

Interrupt Manager

Prototype

void *adi_int_EnterCriticalRegion(
void *pArg
);

Arguments

pArg Implementation dependent. Refer to the adi_int_xxx.h

file for details on this parameter for the

xxx environment.

Return Value

The return value from this function should always be passed to the corre­sponding adi_int_ExitCriticalRegion function.

Device Drivers and System Services Manual for Blackfin Processors 2-27

Interrupt Manager API Reference

adi_int_ExitCriticalRegion

Description

This function removes the condition that was established by the adi_int_

EnterCriticalRegion

to protect a critical region of code. These functions
should be used to bracket a section of code that needs protection from
other processing. These functions should be used sparingly and only when
critical regions of code need protecting.

The pArg parameter that is passed to this function should always be the
return value from the corresponding

adi_int_EnterCriticalRegion

function.

See the adi_int_EnterCriticalRegion function for more information.

Prototype

void adi_int_ExitCriticalRegion(
void *pArg
);

Arguments

pArg The return value from the corresponding adi_int_

EnterCriticalRegion()

function call.

Return Value

None

2-28 Device Drivers and System Services Manual for Blackfin Processors

Interrupt Manager

adi_int_SICDisable

Description

This function configures the System Interrupt Controller to disable the
given interrupt and prevent it from being passed to the Core Event
Controller.

The adi_int_SICDisable function simply programs the System Interrupt
Mask register to mask interrupts from the given peripheral, thereby pre
venting them from being passed to the Core Event Controller.

Prototype

ADI_INT_RESULT adi_int_SICDisable(
const ADI_INT_PERIPHERAL_ID PeripheralID
);

-

Arguments

PeripheralID This is the ADI_INT_PERIPHERAL_ID enumeration value

that identifies an interrupt source.

Return Value

ADI_INT_RESULT_SUCCESS The System Interrupt Controller has been successfully

configured.

ADI_INT_RESULT_INVALID_
PERIPHERALID

The peripheral ID specified is invalid.

Device Drivers and System Services Manual for Blackfin Processors 2-29

Interrupt Manager API Reference

adi_int_SICEnable

Description

This function configures the System Interrupt Controller to enable the
given interrupt and allow it to be passed to the Core Event Controller.

The adi_int_SICEnable function simply programs the System Interrupt
Mask register to allow interrupts from the given peripheral to be passed to
the Core Event Controller.

Prototype

ADI_INT_RESULT adi_int_SICEnable(
const ADI_INT_PERIPHERAL_ID PeripheralID,
);

Arguments

PeripheralID This is the ADI_INT_PERIPHERAL_ED enumeration value

that identifies a peripheral interrupt source.

Return Value

Return values include:

ADI_INT_RESULT_SUCCESS The System Interrupt Controller has been successfully

configured.

ADI_INT_RESULT_INVALID_
PERIPHERAL_ID

The peripheral ID specified is invalid.

2-30 Device Drivers and System Services Manual for Blackfin Processors

Interrupt Manager

adi_int_SICGetIVG

Description

This function detects the mapping of a peripheral interrupt source to an
IVG level. When called, this function reads the appropriate System Inter
rupt Assignment register(s) of the given peripheral and stores the IVG
level to which the peripheral is mapped into the location provided by the
application. This function does not modify any parameters of the inter
rupt controller.

Prototype

ADI_INT_RESULT adi_int_SICSetIVG(
const ADI_INT_PERIPHERAL_ID PeripheralID,
u32 *pIVG
);

-

-

Arguments

PeripheralID The ADI_INT_PERIPHERAL_ID enumeration value that

identifies a peripheral interrupt source

*pIVG The pointer to an unsigned 32-bit memory location into

which the function writes the IVG level to which the given
peripheral is mapped.

Return Value

The function returns ADI_INT_RESULT_SUCCESS if successful. Other possi­ble return values include:

ADI_INT_RESULT_INVALID_
PERIPHERAL_ID

ADI_INT_RESULT_INVALID_IVG The interrupt vector group level is invalid.

The peripheral ID specified is invalid.

Device Drivers and System Services Manual for Blackfin Processors 2-31

Interrupt Manager API Reference

adi_int_SICInterruptAsserted

Description

This function determines if a given peripheral interrupt source is asserting
an interrupt. This function is typically called in an application’s interrupt
handler to determine if the peripheral in question is asserting an interrupt.
This function does not modify any parameters of the interrupt controller
but simply interrogates the appropriate interrupt status register(s).

Prototype

ADI_INT_RESULT adi_int_SICInterruptAsserted(
const ADI_INT_PERIPHERAL_ID PeripheralID
);

Arguments

PeripheralID The ADI_INT_PERIPHERAL_ID enumeration value that

identifies a peripheral interrupt source.

Return Value

The function returns one of the following values:

ADI_INT_RESULT_INVALID_
PERIPHERAL_ID

ADI_INT_RESULT_ASSERTED The specified peripheral is asserting an interrupt.

ADI_INT_RESULT_NOT_ASSERTED The specified peripheral is not asserting an interrupt.

The peripheral ID specified is invalid.

2-32 Device Drivers and System Services Manual for Blackfin Processors

Interrupt Manager

adi_int_SICSetIVG

Description

This function sets the mapping of a peripheral interrupt source to an IVG
level. When called, this function modifies the appropriate System Inter
rupt Assignment register(s) of the given peripheral to the specified IVG
level. This function does not enable or disable interrupts.

Prototype

ADI_INT_RESULT adi_int_SICSetIVG(
const ADI_INT_PERIPHERAL_ID PeripheralID,
const u32 IVG
);

Arguments

-

PeripheralID The ADI_INT_PERIPHERAL_ID enumeration value that

identifies a peripheral interrupt source

IVG The interrupt vector group that the peripheral to which

the peripheral is being assigned.

Return Value

The function returns ADI_INT_RESULT_SUCCESS, if successful. Other possi­ble return values include:

ADI_INT_RESULT_INVALID_
PERIPHERAL_ID

ADI_INT_RESULT_INVALID_IVG The interrupt vector group level is invalid.

The peripheral ID specified is invalid.

Device Drivers and System Services Manual for Blackfin Processors 2-33

Interrupt Manager API Reference

adi_int_SetIMaskBits

Description

This function is used by the Interrupt Manager to set bits in the IMASK
register. Though it can also be called by the application, the application
should not attempt to modify bits in the

IMASK register that represent

interrupt vector groups that are under the control of the Interrupt
Manager.

The implementation of this function is dependent upon the operating
environment. In the standalone version of the service, this function
detects if the processor is within a protected region of code (see the

int_EnterCriticalRegion and adi_int_ExitCriticalRegion functions).

If it is, the saved value of IMASK is updated accordingly and the current
“live” IMASK value is left unchanged. When the outermost adi_int_Exit-

CriticalRegion 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.

adi_

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. Application software does
not have to change when moving to a different operating environment.

Prototype

void adi_int_SetIMASKBits(
ADI_INT_IMASK BitsToSet
);

2-34 Device Drivers and System Services Manual for Blackfin Processors

Interrupt Manager

Arguments

BitsToSet Replica of the IMASK register containing bits that are to

be set in the real IMASK register. A bit with a value of ‘1’
sets 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

Device Drivers and System Services Manual for Blackfin Processors 2-35

Interrupt Manager API Reference

adi_int_SICWakeup

Description

This function configures the System Interrupt Controller Wakeup register
to enable or disable the given peripheral interrupt from waking up the
core processor.

The adi_int_SICWakeup function simply programs the System Interrupt
Controller Wakeup register accordingly. The actual servicing of interrupts
is not affected by this function.

Prototype

ADI_INT_RESULT adi_int_SICWakeup(
const ADI_INT_PERIPHERAL_ID PeripheralID,
u32 WakeupFlag
);

Arguments

PeripheralID This is the ADI_INT_PERIPHERAL_ID enumeration value

that identifies a peripheral interrupt source.

WakeupFlag Enables/disables waking up the core(s) upon triggering of

the peripheral interrupt (TRUE/FALSE).

Return Value

Return values include:

ADI_INT_RESULT_SUCCESS The System Interrupt Controller has been successfully

configured.

ADI_INT_RESULT_INVALID_
PERIPHERAL_ID

The peripheral ID specified is invalid.

2-36 Device Drivers and System Services Manual for Blackfin Processors

3 POWER MANAGEMENT

MODULE

This chapter describes the Power Management (PM) module that sup­ports Dynamic Power Management of Blackfin processors.

This chapter contains:

• “Introduction” on page 3-2

• “PM Module Operation – Getting Started” on page 3-3

• “Power Management API Reference” on page 3-6

• “Public Data Types and Enumerations” on page 3-30

• “PM Module Macros” on page 3-51

Device Drivers and System Services Manual for Blackfin Processors 3-1

Introduction

Introduction

The Power Management (PM) module provides access to all aspects of
Dynamic Power Management:

• Dynamic switching from one operating mode to another: Full-On,
Active, Sleep, Deep Sleep and Hibernate.

• Dynamic setting of voltage levels and clock frequencies to ensure
that an application can be tuned to achieve the best performance
while minimizing power consumption.

• When coupled with the EBIU module*, it enables the SDRAM set­tings to be adjusted upon changes to the system clock to ensure
that the best performance is obtained for the complete system.

The module supports two strategies for setting the core and system clock
frequencies:

• For a given voltage level, the core clock (CCLK) is set to the highest
available frequency. The system clock (

SCLK) is set accordingly.

• For a given combination of core and system clock frequencies, the
valid values nearest to the chosen ones are used and the voltage
level of the processor adjusted accordingly.

In both cases validity checks are performed at all stages, making it impos­sible to stall or harm the processor.

“PM Module Operation – Getting Started” describes the basic operating

stages required to use the Power Management module.

*

See Chapter 3, “External Bus Interface Unit Module” for more information.

3-2 Device Drivers and System Services Manual for Blackfin Processors

Power Management Module

The Power Management Module uses an unambiguous naming conven­tion to safeguard against conflicts with other software libraries provided
by Analog Devices, Inc. or other companies. To this end, all enumeration
values and
variables use the lower case,

typedefs use the ADI_PWR_ prefix, while functions and global

adi_pwr_ equivalent.

Two versions of the library exist for each processor. These correspond to
the debug and release configurations in VisualDSP++ Release 4.0. In addi
tion to the usual defaults for the debug configuration, the API functions
perform checks on the arguments passed and report appropriate error
codes, as required. In the release version of the library, most functions
return one of two result codes:
completion, or

ADI_PWR_RESULT_CALL_IGNORED if the PM module has not

ADI_PWR_RESULT_SUCCESS on successful

been initialized prior to the function call.

PM Module Operation – Getting Started

-

A following example illustrates how to use the PM module to configure a
600Mz ADSP-BF533 processor on an EZ-KIT Lite board to run at the
requested core and system clock frequencies or to minimize power con

-

sumption by pegging the voltage level at 0.95 V.

Step 1:

Initialize the module by setting the parameters for the hardware configura­tion used. In the following example it is assumed that the ADSP-BF533
EZ-KIT Lite (Rev 1.3) is to be configured. The simplest way is to specify
the EZ-KIT board as follows:

ADI_PWR_COMMAND_PAIR ezkit_pwr[] = {
// ADSP-BF533 EZ-KIT LITE REV 1.3
{ ADI_PWR_CMD_SET_EZKIT, ADI_PWR_EZKIT_BF533_600MHz },
{ ADI_PWR_CMD_END, 0 }
};

adi_pwr_Init(ezkit_pwr);

Device Drivers and System Services Manual for Blackfin Processors 3-3

PM Module Operation – Getting Started

To illustrate what is required for non EZ-Kit boards, the above command
table is included an abbreviated form of the following code:

ADI_PWR_COMMAND_PAIR ezkit_pwr[] = {
/* 600Mhz ADSP-BF533 variant *
{ ADI_PWR_CMD_SET_PROC_VARIANT,(void*)ADI_PWR_PROC_
BF533SKBC600 },
/* in MBGA packaging, as on all EZ-KITS */
{ ADI_PWR_CMD_SET_PACKAGE, (void*)ADI_PWR_PACKAGE_MBGA },
/* External Voltage supplied to the */
/*voltage regulator is 3.3V */
{ ADI_PWR_CMD_SET_VDDEXT, (void*)ADI_PWR_VDDEXT_330 },
/* The CLKIN frequency */
(ADI_PWR_CLKIN_EZKIT=27Mhz */
{ ADI_PWR_CMD_SET_CLKIN, (void*)ADI_PWR_CLKIN_
EZKIT_REV_1_5 },
/* command to terminate the table */
{ ADI_PWR_CMD_END, 0 }
};
adi_pwr_Init(ezkit_pwr);

Step 2:

If used in conjunction with the EBIU controller to adjust SDRAM set­tings, the EBIU module is initialized (for EZ-KIT) with the following call:

ADI_EBIU_COMMAND_PAIR ezkit_ebiu[] = {
{ ADI_EBIU_CMD_SET_EZKIT,(void*)ADI_EBIU_EZKIT_BF533 },
{ ADI_EBIU_CMD_END, 0 }
};
adi_ebiu_Init(
ezkit_ebiu, // default is EZ-KIT
FALSE // Do not adjust refresh settings
);

3-4 Device Drivers and System Services Manual for Blackfin Processors

Power Management Module

Step 3:

Decide on which power management strategy to implement. For example,
the following code segments demonstrate how to configure the PM mod
ule for optimal speed or optimal power consumption.

Optimal Speed

The following statement requests that the PM module set the core and
system clock frequencies to the maximum values possible:

adi_pwr_SetFreq(
0, // Core clock frequency (MHz)
0, // System clock frequency (MHz)
ADI_PWR_DF_ON // Do not adjust the PLL input divider
);

Optimal Power Consumption

The following statement requests that the PM module set the core and
system clock frequencies to the maximum that can be sustained at a volt

-

age level of 0.85 V:

-

adi_pwr_SetMaxFreqForVolt(ADI_PWR_VLEV_085);

Device Drivers and System Services Manual for Blackfin Processors 3-5

Power Management API Reference

Power Management API Reference

This section provides descriptions of the PM module’s Application Pro­gramming Interface (API) functions.

Notation Conventions

The reference pages for the API functions use the following format:

Name and purpose of the function

Description – Function specification

Prototype – Required header file and functional prototype

Arguments – Description of function arguments

Return Value – Description of function return values

3-6 Device Drivers and System Services Manual for Blackfin Processors

Power Management Module

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

page 3-35). The divider value cannot exceed the ssel value.

“ADI_PWR_CSEL” on

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_SSEL” on page 3-44).

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

ADI_PWR_RESULT_INVALID_
CSEL

The PM module has not been initialized.

An invalid value for CSEL has been specified.

Device Drivers and System Services Manual for Blackfin Processors 3-7

Power Management API Reference

ADI_PWR_RESULT_INVALID_
SSEL

ADI_PWR_INVALID_CSEL_
SSEL_COMBINATION

An invalid value for SSEL has been specified.

The core clock divider is greater that the System clock
divider value, or both

SSEL_NONE

are specified.

ADI_PWR_CSEL_NONE and ADI_PWR_

3-8 Device Drivers and System Services Manual for Blackfin Processors

Power Management Module

adi_pwr_Control

Description

This function enables the Dynamic Power Management registers to be
configured or queried according to command-value pairs
(“ADI_PWR_COMMAND_PAIR” on page 3-35), 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_PWR_INPUT_DELAY_ENABLE,

);

2. A single command-value pair structure is passed.

ADI_PWR_COMMAND_PAIR cmd = {
ADI_PWR_CMD_SET_INPUT_DELAY,
(void*)ADI_PWR_INPUT_DELAY_ENABLE,

};
adi_pwr_Control(ADI_PWR_CMD_PAIR,(void*)&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_PWR_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_PWR_CMD_END, 0}
};

adi_pwr_Control(
ADI_PWR_CMD_TABLE,
(void*)table

);

Device Drivers and System Services Manual for Blackfin Processors 3-9

Power Management API Reference

Refer to ADI_PWR_COMMAND on page 3-31 and “Public Data Types and Enu-

merations” on page 3-30 for the complete list of commands and associated

values.

Prototype

ADI_PWR_RESULT adi_pwr_Control(
ADI_PWR_COMMAND command,

void *Value
);

Arguments

Command An ADI_PWR_COMMAND enumeration value specifies the

meaning of the associated value argument.

Value This is the required value (see “ADI_PWR_COMMAND”

on page 3-31).

Return Value

In debug mode the adi_pwr_Control function returns one of the following
values. Otherwise,

ADI_PWR_RESULT_SUCCESS This function completed successfully.

ADI_PWR_RESULT_BAD_COM­MAND

ADI_PWR_RESULT_CALL_
IGNORED

ADI_PWR_RESULT_INVALID_
INPUT_DELAY

ADI_PWR_RESULT_INVALID_
OUTPUT_DELAY

ADI_PWR_RESULT_INVALID_
LOCKCNT

ADI_PWR_RESULT_SUCCESS is returned.

An invalid command has been specified.

The PM module has not been initialized.

The input delay value is invalid.

The output delay value is invalid.

The PLL lock count value is invalid.

3-10 Device Drivers and System Services Manual for Blackfin Processors

Power Management Module

adi_pwr_GetConfigSize

Description

This function returns the number of bytes required to save the current
configuration data. This value is also available via the

CONFIG

macro.

ADI_PWR_SIZEOF_

The return value of adi_pwr_GetConfigSize as well the ADI_PWR_SIZEOF_

CONFIG

macro incorporate the size of the EBIU Module configuration,

whether the latter is initialized or not.

Prototype

size_t adi_pwr_GetConfigSize(void);

Return Value

The size of the configuration structure.

Device Drivers and System Services Manual for Blackfin Processors 3-11

Power Management API Reference

adi_pwr_GetFreq

Description

This function returns the current values of the CCLK, SCLK and Voltage
Core Oscillator (VCO) frequencies

Prototype

ADI_PWR_RESULT adi_pwr_GetFreq(
u32 *fcclk,
u32 *fsclk,
u32 *fvco);

Arguments

fcclk This is an address of location to store the current CCLK

value (MHz).

fsclk This is an address of location to store the current SCLK value

(MHz).

fvco This is an address of location to store the VCO frequency

(MHz).

Return Value

In the debug variant of the library, the function adi_pwr_GetFreq 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.

3-12 Device Drivers and System Services Manual for Blackfin Processors