ANALOG DEVICES W4.5 Service Manual

Download

Page 1

W4.5

Device Drivers and System Services Manual

for Blackfin® Processors

Analog Devices, Inc.

Revision 2.1, August 2006

Part Number

82-000430-01

Page 2

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.

Page 3

PREFACE

Purpose of This Manual ................................................................ xxv

Intended Audience ........................................................................ xxv

Manual Contents Description ...................................................... xxvi

Technical or Customer Support ................................................... xxvii

Supported Processors .................................................................. xxviii

Product Information .................................................................. xxviii

MyAnalog.com ..................................................................... xxviii

Processor Product Information ................................................ xxix

Related Documents ................................................................ xxix

Online Technical Documentation ............................................ xxx

Accessing Documentation From the Web ............................. xxx

Viewing Help Files ............................................................. xxxi

Printed Manuals ..................................................................... xxxi

VisualDSP++ Documentation Set ....................................... xxxi

Hardware Tools Manuals ................................................... xxxii

Processor Manuals ............................................................. xxxii

Data Sheets ....................................................................... xxxii

Notation Conventions ................................................................. xxxii

VisualDSP++ 4.5 Device Drivers and System iii Services Manual for Blackfin Processors

Page 4

CONTENTS

INTRODUCTION

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

General ................................................................................... 1-3

Application Interface ............................................................... 1-7

Dependencies .......................................................................... 1-8

Initialization ......................................................................... 1-10

Termination .......................................................................... 1-10

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

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

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

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

Examples .......................................................................... 1-16

Dual Core Considerations ................................................. 1-16

RTOS Considerations ................................................................. 1-17

Interoperability of System Services with VDK ........................ 1-17

Deployment of Services within a multi-threaded application .. 1-19

Device Driver Overview .............................................................. 1-20

Application Interface ............................................................. 1-21

Device Driver Architecture .................................................... 1-22

Interaction with System Services ....................................... 1-24

Initialization ......................................................................... 1-24

Termination .......................................................................... 1-24

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

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

iv VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 5

CONTENTS

Device Driver File Locations ............................................. 1-27

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

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

Examples on Distribution .................................................. 1-31

INTERRUPT MANAGER

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

Interrupt Manager Initialization .................................................... 2-4

Interrupt Manager Termination ..................................................... 2-5

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

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

adi_int_CECUnhook() Function ............................................. 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-10

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

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

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

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

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

File Structure .............................................................................. 2-15

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

VisualDSP++ 4.5 Device Drivers and System v Services Manual for Blackfin Processors

Page 6

CONTENTS

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

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

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

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

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

Dual Core Considerations ............................................................. 3-7

Simple Method of Making it Work .......................................... 3-7

Synchronization Requirement .................................................. 3-8

Running Applications on One Core Only ................................ 3-9

Running Applications on Both Cores ..................................... 3-10

Synchronization between Cores ............................................. 3-11

vi VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 7

CONTENTS

The Built-in Lock variable and Linking Considerations .......... 3-12

SDRAM Initialization Prior to Loading an Executable ................. 3-15

Power Management API Reference .............................................. 3-18

Notation Conventions ........................................................... 3-18

adi_pwr_AdjustFreq .............................................................. 3-19

adi_pwr_Control ................................................................... 3-21

adi_pwr_GetConfigSize ......................................................... 3-23

adi_pwr_GetFreq .................................................................. 3-24

adi_pwr_GetPowerMode ....................................................... 3-25

adi_pwr_GetPowerSaving ...................................................... 3-26

adi_pwr_Init ......................................................................... 3-27

adi_pwr_LoadConfig ............................................................. 3-33

adi_pwr_Reset ....................................................................... 3-35

adi_pwr_SaveConfig .............................................................. 3-36

adi_pwr_SetFreq ................................................................... 3-37

adi_pwr_SetMaxFreqForVolt ................................................. 3-39

adi_pwr_SetPowerMode ........................................................ 3-40

adi_pwr_SetVoltageRegulator ................................................ 3-42

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

ADI_PWR_COMMAND ..................................................... 3-46

ADI_PWR_COMMAND_PAIR ........................................... 3-52

ADI_PWR_CSEL ................................................................. 3-53

ADI_PWR_DF ..................................................................... 3-54

ADI_PWR_EZKIT ............................................................... 3-55

VisualDSP++ 4.5 Device Drivers and System vii Services Manual for Blackfin Processors

Page 8

CONTENTS

ADI_PWR_INPUT_DELAY ................................................ 3-56

ADI_PWR_OUTPUT_DELAY ............................................ 3-57

ADI_PWR_MODE .............................................................. 3-58

ADI_PWR_PACKAGE_KIND ............................................. 3-59

ADI_PWR_PCC133_COMPLIANCE .................................. 3-60

ADI_PWR_PROC_KIND .................................................... 3-61

ADI_PWR_RESULT ............................................................ 3-62

ADI_PWR_SSEL .................................................................. 3-64

ADI_PWR_VDDEXT .......................................................... 3-65

ADI_PWR_VLEV ................................................................ 3-66

ADI_PWR_VR_CANWE ..................................................... 3-67

ADI_PWR_VR_CKELOW ................................................... 3-68

ADI_PWR_VR_CLKBUFOE ............................................... 3-69

ADI_PWR_VR_FREQ ......................................................... 3-70

ADI_PWR_VR_GAIN ......................................................... 3-71

ADI_PWR_VR_PHYWE ..................................................... 3-72

ADI_PWR_VR_WAKE ........................................................ 3-73

PM Module Macros .................................................................... 3-74

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

viii VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 9

CONTENTS

adi_ebiu_Control .................................................................... 4-9

adi_ebiu_GetConfigSize ........................................................ 4-12

adi_ebiu_Init ........................................................................ 4-13

adi_ebiu_LoadConfig ............................................................ 4-17

adi_ebiu_SaveConfig ............................................................. 4-18

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

ADI_EBIU_RESULT ............................................................ 4-20

ADI_EBIU_SDRAM_BANK_VALUE ................................... 4-22

ADI_EBIU_TIME ................................................................ 4-23

ADI_EBIU_TIMING_VALUE ............................................. 4-24

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

ADI_EBIU_COMMAND ..................................................... 4-25

ADI_EBIU_COMMAND_PAIR ........................................... 4-29

Command Value Enumerations ............................................. 4-29

ADI_EBIU_SDRAM_EZKIT ........................................... 4-29

ADI_EBIU_SDRAM_ENABLE ........................................ 4-29

ADI_EBIU_SDRAM_BANK_SIZE .................................. 4-30

ADI_EBIU_SDRAM_BANK_COL_WIDTH ................... 4-30

ADI_EBIU_SDRAM_MODULE_TYPE .......................... 4-31

ADI_EBIU_CMD_SET_SDRAM_SCTLE ....................... 4-32

ADI_EBIU_SDRAM_EMREN ......................................... 4-33

ADI_EBIU_SDRAM_PASR ............................................. 4-33

ADI_EBIU_SDRAM_TCSR ............................................. 4-33

ADI_EBIU_SDRAM_SRFS .............................................. 4-34

VisualDSP++ 4.5 Device Drivers and System ix Services Manual for Blackfin Processors

Page 10

CONTENTS

ADI_EBIU_SDRAM_EBUFE .......................................... 4-34

ADI_EBIU_SDRAM_PUPSD .......................................... 4-35

ADI_EBIU_SDRAM_PSM .............................................. 4-35

ADI_EBIU_SDRAM_FBBRW ......................................... 4-36

ADI_EBIU_SDRAM_CDDBG ........................................ 4-36

DEFERRED CALLBACK MANAGER

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

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

Interoperability With an RTOS ..................................................... 5-8

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

adi_dcb_RegisterISR ............................................................. 5-10

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

DCB Manager API Reference ...................................................... 5-12

Notation Conventions ........................................................... 5-12

adi_dcb_Close ...................................................................... 5-13

adi_dcb_Control ................................................................... 5-14

adi_dcb_Init ......................................................................... 5-17

adi_dcb_Open ...................................................................... 5-19

adi_dcb_Post ........................................................................ 5-21

adi_dcb_Remove ................................................................... 5-24

adi_dcb_Terminate ............................................................... 5-25

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

ADI_DCB_CALLBACK_FN ................................................ 5-27

ADI_DCB_COMMAND_PAIR ........................................... 5-28

x VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 11

ADI_DCB_COMMAND ...................................................... 5-29

ADI_DCB_ENTRY_HDR .................................................... 5-30

ADI_DCB_RESULT ............................................................. 5-31

DMA MANAGER

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

Theory of Operation ..................................................................... 6-4

Overview ................................................................................ 6-4

DMA Manager Initialization ................................................... 6-5

DMA Manager Termination ................................................... 6-6

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

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

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

Memory Transfers ............................................................... 6-8

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

Two-Dimensional Transfers ........................................... 6-10

Closing Memory Streams .................................................. 6-11

Controlling DMA Channels .................................................. 6-11

Opening DMA Channels .................................................. 6-11

Single Transfers ............................................................. 6-13

Circular Transfers .......................................................... 6-15

Large Descriptor Chaining Model .................................. 6-17

Small Descriptor Chaining Model ................................. 6-21

Arrays of Descriptors ..................................................... 6-21

Configuring a DMA Channel ............................................ 6-22

VisualDSP++ 4.5 Device Drivers and System xi Services Manual for Blackfin Processors

Page 12

Closing a DMA Channel .................................................. 6-22

Transfer Completions ............................................................ 6-23

Polling ............................................................................. 6-23

Callbacks .......................................................................... 6-23

Memory Stream Callbacks ............................................ 6-24

Circular Transfer Callbacks ........................................... 6-24

Descriptor Callbacks ..................................................... 6-25

Descriptor-Based Sub-Modes ................................................. 6-25

Loopback Sub-Mode ......................................................... 6-25

Streaming Sub-Mode ........................................................ 6-26

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

Sensing a Mapping ........................................................... 6-28

Setting a Mapping ............................................................ 6-28

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

Hooking Interrupts ........................................................... 6-29

Unhooking Interrupts ....................................................... 6-29

Two-Dimensional DMA ........................................................ 6-30

DMA manager API Reference ..................................................... 6-33

Notation Conventions ........................................................... 6-33

adi_dma_Buffer .................................................................... 6-35

adi_dma_Close ..................................................................... 6-37

adi_dma_Control .................................................................. 6-38

adi_dma_GetMapping .......................................................... 6-41

adi_dma_Init ........................................................................ 6-42

xii VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 13

adi_dma_MemoryClose ......................................................... 6-43

adi_dma_MemoryCopy ......................................................... 6-44

adi_dma_MemoryCopy2D .................................................... 6-46

adi_dma_MemoryOpen ......................................................... 6-48

adi_dma_Open ..................................................................... 6-50

adi_dma_Queue .................................................................... 6-53

adi_dma_SetMapping ............................................................ 6-54

adi_dma_Terminate ............................................................... 6-55

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

Data Types ............................................................................ 6-57

ADI_DMA_CHANNEL_HANDLE ................................. 6-57

ADI_DMA_DESCRIPTOR_UNION/ADI_DMA_DESCRIPTOR_

HANDLE ...................................................................... 6-57

ADI_DMA_STREAM_HANDLE .................................... 6-58

Data Structures ..................................................................... 6-58

ADI_DMA_2D_TRANSFER ........................................... 6-58

ADI_DMA_CONFIG_REG ............................................. 6-59

ADI_DMA_DESCRIPTOR_ARRAY ................................ 6-59

ADI_DMA_DESCRIPTOR_LARGE ................................ 6-59

ADI_DMA_DESCRIPTOR_SMALL ................................ 6-60

General Enumerations ........................................................... 6-60

ADI_DMA_CHANNEL_ID ............................................ 6-60

ADI_DMA_EVENT ......................................................... 6-60

ADI_DMA_MODE ......................................................... 6-61

ADI_DMA_PMAP ........................................................... 6-61

VisualDSP++ 4.5 Device Drivers and System xiii Services Manual for Blackfin Processors

Page 14

ADI_DMA_RESULT ....................................................... 6-62

ADI_DMA_STREAM_ID ............................................... 6-62

ADI_DMA_CONFIG_REG Field Values .............................. 6-63

ADI_DMA_DMA2D ....................................................... 6-63

ADI_DMA_DI_EN ......................................................... 6-63

ADI_DMA_DI_SEL ........................................................ 6-63

ADI_DMA_EN ............................................................... 6-63

ADI_DMA_WDSIZE ...................................................... 6-63

ADI_DMA_WNR ............................................................ 6-64

DMA Commands ................................................................. 6-64

PROGRAMMABLE FLAG SERVICE

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

Operation .................................................................................... 7-3

Initialization ........................................................................... 7-4

Termination ............................................................................ 7-4

Flag IDs .................................................................................. 7-5

Flag Control Functions ........................................................... 7-5

adi_flag_Open() ................................................................. 7-5

adi_flag_Close() ................................................................. 7-5

adi_flag_SetDirection() ....................................................... 7-6

adi_flag_Set() ..................................................................... 7-6

adi_flag_Clear() .................................................................. 7-6

adi_flag_Toggle() ................................................................ 7-6

adi_flag_Sense() ................................................................. 7-6

xiv VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 15

Callbacks ................................................................................ 7-6

adi_flag_InstallCallback() .................................................... 7-7

adi_flag_RemoveCallback() ................................................. 7-9

adi_flag_SuspendCallbacks() ............................................... 7-9

adi_flag_ResumeCallbacks() ................................................ 7-9

adi_flag_SetTrigger() ........................................................... 7-9

Coding Example ...................................................................... 7-9

Initialization ..................................................................... 7-10

Opening a Flag ................................................................. 7-10

Setting the Direction ......................................................... 7-11

Controlling an Output Flag ............................................... 7-11

Sensing the Value of a Flag ................................................ 7-12

Installing a Callback Function ........................................... 7-12

Suspending and Resuming Callbacks ................................. 7-13

Removing Callbacks .......................................................... 7-13

Termination ...................................................................... 7-14

Flag Service API Reference .......................................................... 7-14

Notation Conventions ........................................................... 7-14

adi_flag_Clear ....................................................................... 7-15

adi_flag_Close ....................................................................... 7-16

adi_flag_Init ......................................................................... 7-17

adi_flag_Open ....................................................................... 7-19

adi_flag_SetDirection ............................................................ 7-20

adi_flag_Terminate ................................................................ 7-21

VisualDSP++ 4.5 Device Drivers and System xv Services Manual for Blackfin Processors

Page 16

adi_flag_Set .......................................................................... 7-22

adi_flag_Toggle ..................................................................... 7-23

adi_flag_Sense ...................................................................... 7-24

adi_flag_InstallCallback ........................................................ 7-25

adi_flag_RemoveCallback ...................................................... 7-27

adi_flag_SuspendCallbacks .................................................... 7-28

adi_flag_ResumeCallbacks .................................................... 7-29

adi_flag_SetTrigger ............................................................... 7-30

Public Data Types, Enumerations and Macros ............................. 7-31

ADI_FLAG_ID .................................................................... 7-31

Associated Macros ............................................................ 7-32

ADI_FLAG_RESULT ........................................................... 7-32

ADI_FLAG_EVENT ............................................................ 7-33

ADI_FLAG_TRIGGER ........................................................ 7-33

ADI_FLAG_TRIGGER ........................................................ 7-34

ADI_FLAG_EVENT ............................................................ 7-34

TIMER SERVICE

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

Operation .................................................................................... 8-3

Initialization ........................................................................... 8-3

Termination ............................................................................ 8-4

Timer IDs ............................................................................... 8-4

Basic Timer Functions ............................................................. 8-4

adi_tmr_Open() ................................................................. 8-4

xvi VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 17

adi_tmr_Close() .................................................................. 8-5

adi_tmr_Reset() .................................................................. 8-5

General-Purpose Timer Functions ............................................ 8-5

adi_tmr_GPControl() ......................................................... 8-5

adi_tmr_GPGroupEnable() ................................................. 8-6

Core Timer Functions ............................................................. 8-6

adi_tmr_CoreControl() ....................................................... 8-6

Watchdog Timer Functions ...................................................... 8-6

adi_tmr_WatchdogControl() ............................................... 8-7

Peripheral Timer Functions ...................................................... 8-7

adi_tmr_GetPeripheralID() ................................................. 8-7

Callbacks ................................................................................ 8-7

adi_tmr_InstallCallback() .................................................... 8-8

adi_tmr_RemoveCallback() ................................................. 8-9

Coding Example .................................................................... 8-10

Initialization ..................................................................... 8-10

Opening a Timer .............................................................. 8-10

Configuring a Timer ......................................................... 8-11

Enabling and Disabling Timers ......................................... 8-12

Installing a Callback Function ........................................... 8-13

Removing Callbacks .......................................................... 8-14

Termination ...................................................................... 8-15

Timer Service API Reference ....................................................... 8-16

Notation Conventions ........................................................... 8-16

VisualDSP++ 4.5 Device Drivers and System xvii Services Manual for Blackfin Processors

Page 18

adi_tmr_Init ......................................................................... 8-17

adi_tmr_Open ...................................................................... 8-18

adi_tmr_Terminate ............................................................... 8-19

adi_tmr_Close ...................................................................... 8-20

adi_tmr_Reset ....................................................................... 8-21

adi_tmr_CoreControl ........................................................... 8-22

adi_tmr_WatchdogControl ................................................... 8-23

adi_tmr_GPControl .............................................................. 8-24

adi_tmr_GPGroupEnable ..................................................... 8-25

adi_tmr_InstallCallback ........................................................ 8-27

adi_tmr_RemoveCallback ..................................................... 8-29

adi_tmr_GetPeripheralID ...................................................... 8-30

Public Data Types, Enumerations and Macros ............................. 8-31

Timer IDs ............................................................................. 8-31

Associated Macros ............................................................ 8-32

ADI_TMR_RESULT ............................................................ 8-32

ADI_TMR_EVENT ............................................................. 8-33

ADI_TMR_CORE_CMD .................................................... 8-33

ADI_TMR_WDOG_CMD .................................................. 8-34

ADI_TMR_GP_CMD .......................................................... 8-35

PORT CONTROL SERVICE

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

Using the Port Control Manager ................................................... 9-2

Port Control Manager API Reference ............................................ 9-4

xviii VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 19

Notation Conventions ............................................................. 9-5

adi_ports_Init ......................................................................... 9-6

adi_ports_Terminate ................................................................ 9-7

adi_ports_EnablePPI ............................................................... 9-8

adi_ports_EnableSPI ............................................................... 9-9

adi_ports_EnableSPORT ....................................................... 9-10

adi_ports_EnableUART ......................................................... 9-11

adi_ports_EnableCAN ........................................................... 9-12

adi_ports_EnableTimer ......................................................... 9-13

adi_ports_EnableGPIO ......................................................... 9-15

Public Data Types, Enumerations and Macros .............................. 9-17

ADI_PORTS_RESULT ......................................................... 9-17

Directive Enumeration Values ................................................ 9-17

DEVICE DRIVER MANAGER

Device Driver Model Overview ................................................... 10-4

Using the Device Manager .......................................................... 10-7

Device Manager Overview ..................................................... 10-7

Theory of Operation ............................................................. 10-8

Data ................................................................................. 10-9

Initializing the Device Manager ....................................... 10-10

Device Manager Termination .......................................... 10-11

Opening a Device ........................................................... 10-11

Configuring a Device ...................................................... 10-12

Dataflow Method ........................................................ 10-13

VisualDSP++ 4.5 Device Drivers and System xix Services Manual for Blackfin Processors

Page 20

Enabling Dataflow ...................................................... 10-16

Providing Buffers to a Device .......................................... 10-16

Closing a Device ............................................................. 10-18

Callbacks ........................................................................ 10-18

Initialization Sequence .................................................... 10-18

Stackable Drivers ............................................................ 10-19

Deciding on a Dataflow Method ............................................... 10-20

Chained without Loopback ................................................. 10-20

Chained with Loopback ...................................................... 10-20

Circular ............................................................................. 10-20

Sequential With and Without Loopback .............................. 10-21

Creating One Dimensional Buffers ........................................... 10-21

Creating Two Dimensional Buffers ............................................ 10-25

Creating Circular Buffers .......................................................... 10-28

Creating One Dimensional Sequential Buffers ........................... 10-30

Device Manager Design ............................................................ 10-32

Device Manager API Description ......................................... 10-33

Memory Usage Macros ................................................... 10-34

Handles .......................................................................... 10-34

Dataflow Enumerations .................................................. 10-34

Command IDs ............................................................... 10-35

Callback Events .............................................................. 10-35

Return Codes ................................................................. 10-35

Circular Buffer Callback Options .................................... 10-36

xx VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 21

Buffer Data Types ........................................................... 10-36

Physical Driver Entry Point ............................................. 10-37

API Function Definitions ................................................ 10-37

Device Manager Code ......................................................... 10-37

Data Structures ............................................................... 10-37

Static Data ...................................................................... 10-38

Static Function Declarations ............................................ 10-38

API Functional Description ............................................. 10-38

adi_dev_Init Functional Description ........................... 10-39

adi_dev_Open Functional Description ........................ 10-39

adi_dev_Close Functional Description ......................... 10-40

adi_dev_Read Functional Description .......................... 10-40

adi_dev_Write Functional Description ......................... 10-41

adi_dev_Control Functional Description ..................... 10-42

Static Functions .............................................................. 10-45

PDDCallback ............................................................. 10-45

DMACallback ............................................................. 10-45

PrepareBufferList ........................................................ 10-46

SetDataflow ................................................................ 10-48

Physical Driver Design .............................................................. 10-49

Physical Driver Design Overview ......................................... 10-49

Physical Device Driver API Description ............................... 10-51

Physical Driver Include File (“xxx.h”) ................................... 10-52

Extensible Definitions ..................................................... 10-52

VisualDSP++ 4.5 Device Drivers and System xxi Services Manual for Blackfin Processors

Page 22

ADI_DEV_PDD_ENTRY_POINT ................................ 10-54

Physical Driver Source (“xxx.c”) .......................................... 10-54

adi_pdd_Open Functional Description ........................... 10-55

adi_pdd_Control Functional Description ........................ 10-56

adi_pdd_Read Functional Description ............................ 10-58

adi_pdd_Write Functional Description ........................... 10-59

adi_pdd_Close Functional Description ........................... 10-60

Device Manager API Reference ................................................. 10-62

Notation Conventions ......................................................... 10-62

adi_dev_Close ..................................................................... 10-63

adi_dev_Control ................................................................. 10-64

adi_dev_Init ....................................................................... 10-65

adi_dev_Open .................................................................... 10-67

adi_dev_Read ..................................................................... 10-70

adi_dev_Terminate .............................................................. 10-71

adi_dev_Write .................................................................... 10-72

Physical Driver API Reference ................................................... 10-73

Notation Conventions ......................................................... 10-73

adi_pdd_Close .................................................................... 10-74

adi_pdd_Control ................................................................ 10-75

adi_pdd_Open .................................................................... 10-76

adi_pdd_Read ..................................................................... 10-78

adi_pdd_Write .................................................................... 10-79

Examples .................................................................................. 10-80

xxii VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 23

INDEX

VisualDSP++ 4.5 Device Drivers and System xxiii Services Manual for Blackfin Processors

Page 24

xxiv VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 25

PREFACE

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

Purpose of This Manual

The VisualDSP++ 4.5 Device Drivers and System contains 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 Blackfin processors. This manual assumes that the audience has a working knowledge of the appropriate processor architec ture 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.

VisualDSP++ 4.5 Device Drivers and System xxv Services Manual for Blackfin Processors

Page 26

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 supports 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 application developer to effectively execute function calls

• Chapter 6, “DMA Manager” describes direct memory access (DMA) manager API

• Chapter 7, “Programmable Flag Service” describes the programmable flag service that provides interface into the programmable flag subsystem of the Blackfin processor.

• Chapter 8, “Timer Service” describes the Timer Service that provides interface into the core, watchdog and general-purpose timers of the Blackfin processor.

xxvi VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 27

• Chapter 9, “Port Control Service” describes the port control manager service that is used to assign the programmable flag pins to various functions (on ADSP-BF534, ADSP-BF536, and ADSP-BF537 processors only).

• Chapter 10, “Device Driver Manager” describes the device driver model used to control devices, both internal and external, to ADI 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

Preface

• E-mail tools questions to

processor.tools.support@analog.com

• E-mail processor questions to

processor.support@analog.com (World wide support) processor.europe@analog.com (Europe support) processor.china@analog.com (China support)

• Phone questions to 1-800-ANALOGD

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

• Send questions by mail to:

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

VisualDSP++ 4.5 Device Drivers and System xxvii Services Manual for Blackfin Processors

Page 28

Supported Processors

Currently, the following Blackfin processors are supported:

ADSP-BF531 ADSP-BF532 (formerly ADSP-21532) ADSP-BF533 ADSP-BF535 (formerly ADSP-21535) ADSP-BF534 ADSP-BF536 ADSP-BF537 ADSP-BF538 ADSP-BF539 ADSP-BF561 AD6903 AD6531 AD6901 AD6902

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 information about a broad range of products—analog integrated circuits, amplifiers, converters, and digital signal processors.

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:

xxviii VisualDSP++ 4.5 Device Drivers and System

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

Services Manual for Blackfin Processors

Page 29

Preface

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.

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.

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

processor.support@analog.com (World wide support) processor.europe@analog.com (Europe support) processor.china@analog.com (China support)

• Fax questions or requests for information to

1-781-461-3010 (North America) +49-89-76903-157 (Europe)

• Access the FTP Web site at

ftp ftp.analog.com (or ftp 137.71.25.69) ftp://ftp.analog.com

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. For easy printing, supplemen tary .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 5.01 (or higher).

Viewing and printing the Reader (4.0 or higher).

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

Accessing Documentation From the Web

Download manuals in PDF format at the following Web site:

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

xxx VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 31

Preface

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.

Viewing Help Files

VisualDSP++ Help files (.CHM files) are installed in your <install_

path>/Help

directory.

You may download the source files necessary to build the “xchm" .CHM file viewer from

http://xchm.sourceforge.net/. These files are free of

charge.

To view a .CHM file, open a command window and type:

> xchm filename.CHM &

Printed Manuals

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

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.

VisualDSP++ 4.5 Device Drivers and System xxxi Services Manual for Blackfin Processors

Page 32

Product Information

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.

xxxii VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 33

Notation Conventions

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

Example Description

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

brackets and separated by vertical bars; read the example as

that. One or the other is required.

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

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

that

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

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

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

letter gothic font.

this.

Preface

this or

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

Note: For correct operation, ... A Note provides supplementary information on a related topic. In the

L a

[

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.

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.

Additional conventions, which apply only to specific chapters, may

appear throughout this document.

VisualDSP++ 4.5 Device Drivers and System xxxiii Services Manual for Blackfin Processors

Page 34

Notation Conventions

xxxiv VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 35

1 INTRODUCTION

This manual describes the System Services and Device Driver architecture for Analog Devices embedded 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 management (PM), interrupt control (IC), and so on. Collectively, the system services provide a wealth of pre-built, optimized code that simplifies software 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 simplifies the development of device drivers, making it very straightforward for the development of new device drivers.

This chapter contains:

• “System Services Overview” on page 1-2

• “Device Driver Overview” on page 1-20

VisualDSP++ 4.5 Device Drivers and System 1-1 Services Manual for Blackfin Processors

Page 36

System Services Overview

The System Services overview covers the following topics:

• “General”

• “Application Interface” on page 1-7

• “Dependencies” on page 1-8

• “Initialization” on page 1-10

• “Termination” on page 1-10

• “System Services Directory and File Structure” on page 1-11

1-2 VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 37

Introduction

General

The current revision of the System Services library consists of the following 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 a 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 operating modes including, Full-On, Active, Sleep, and so on.

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

Page 38

System Services Overview

• 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-Lite 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 service executes.

• Create multiple callback services, each operating at a different 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 a Blackfin processor. The DMA Management service allows the application to schedule

1-4 VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 39

Introduction

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

• Programmable Flag Service – The programmable flag service pro-

vides a simple interface into the programmable flags, sometimes called General-Purpose I/O, of the Blackfin processor. The func-

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

Page 40

System Services Overview

tionality provided in this service allows the application to access and control the programmable flags through a clean and consistent interface. The programmable flag service allows the application to:

• Configure the direction, either input or output, of any flag.

• Set, clear and toggle the value of all output flags.

• Sense the value of input flags.

• Install callbacks, including both “live” and deferred callbacks, when specific trigger conditions occur on a flag.

• Timer Service – The timer service provides applications, drivers, a

simple mechanism to control the general purpose, core and watch dog timers of the Blackfin processor. The timer service provides the application with the following functionality:

• Configure and control any timer within the processor, including general purpose, core and watchdog timers.

• Install callbacks, including both “live” and deferred callbacks, when timers expire or trigger.

• Port Control Service – Available only on the ADSP-BF534,

ADSP-BF536 and ADSP-BF537 (Braemar) processors, the port control service configures the pin muxing hardware appropriately to insure proper operation of the peripherals that share common input and output pins. All System Services and Device Drivers automatically make the appropriate calls into the port control ser vice to seamlessly configure the pin muxing hardware without any end-user or application interaction, other than initialization of the service.

1-6 VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 41

Introduction

• 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 variety of dataflow methods.

Application Interface

Each system service exports an application programming interface (API) that defines the interface into that service. Application software makes calls into the API of the system service to access the functionality that is to be controlled.

Each API is designed to be called using the standard calling interface of the development toolset’s C run-time model. The API of each service can be called by any C or assembly language program that adheres to the call ing conventions and register usage of the C run-time model.

In addition to the application software using the API to make calls into a system service, some system services make calls into the API of other system services. For the most part, each service operates independently of the other services; however redundancies are eliminated by allowing one ser vice to access the functionality of another service.

For example, should the application need to be notified when a DMA descriptor has completed processing, and the application has requested deferred callbacks. In this case, the DMA Management service invokes the deferred callback service to effect the callback into the application.

Another example of combined operation between services is in the case of the power management and EBIU services. Assume that the system has SDRAM and the application needs to conserve power by turning down

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

Page 42

System Services Overview

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.

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

interactions among them.

EBIU (SDRAM)

Dynamic Power

Interrupt Manager

DMA Manager

Flag Control Timer Control

Port Control

Deferred Callback

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

1-8 VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 43

Introduction

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 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 interrupt-time callbacks) the DMA manager leverages the capabilities of the deferred callback service to provide deferred callbacks to the application. However, when configured for live callbacks, 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.

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

Page 44

System Services Overview

Initialization

Some System Services rely on other System Services and therefore there is a preferred initialization sequence. It is usually preferable to initialize all services together, typically when the whole system is being initialized, rather than spreading out the initialization of various services at different times.

Most applications will find the initialization sequence listed below optimal. Any service in the sequence that is not used by the application can simply be omitted from the sequence.

1. Interrupt control service

2. External bus interface unit

3. Power management service

4. Port control (ADSP-BF534/536/537 processors only)

5. Deferred callback service

6. DMA manager service

7. Programmable flag service

8. Timer service

Termination

Many embedded systems operate continuously in an endless loop so may never need to call the termination function of a service. Applications that do not have a need to terminate a service can save memory by never calling the termination function.

For those applications that do need to terminate services, as with the initialization sequence, there is a preferred sequence of terminating the services.

1-10 VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 45

Introduction

Most applications will find the termination sequence listed below optimal. Any service in the sequence that is not used by the application can simply be omitted from the sequence.

1. Timer service

2. Programmable flag service

3. DMA manager service

4. Deferred callback service

5. Port control (ADSP-BF534/536/537 processors only)

6. Power management service

7. External bus interface unit

8. Interrupt control service

System Services Directory and File Structure

All files for the System Services are contained within the blackfin directory 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

Blackfin/include/services directory in the [compiler and/or assembler]

pre-processor search path. User source files accessing any of the System

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

blackfin directory tree.

Page 46

System Services Overview

Services APIs should simply include the services.h file, located in the

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

any other files to use the System Services API.

The System Services API and functionality are uniform and consistent across all Blackfin 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 Services 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

services.h include file.

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 services.h file 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

__ADSPBF534__ The ADSP-BF534 processor

__ADSPBF535__ The ADSP-BF535 processor

__ADSPBF536__ The ADSP-BF536 processor

__ADSPBF537__ The ADSP-BF537 processor

1-12 VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 47

Introduction

__ADSPBF538__ The ADSP-BF538 processor

__ADSPBF539__ The ADSP-BF539 processor

__ADSPBF561__ The ADSP-BF561 processor

__ADSPBF566__ The ADSP-BF566 processor

...

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

processor variants, the internals of the System Services differ depending on the specific processor variant and processor revision number being targeted. For example, the number of DMA chan nels for the ADSP-BF533 processor differs from the number of DMA channels for the ADSP-BF561 processor. Further, a

Although the API of the System Services does not change between

workaround within the services for revision not be needed for revision

x.y of that same processor. These differ-

x.y of a processor may

ences are accounted for in the System Service Library module. See

“System Services Overview” for more information.

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. This directory provides 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_yyyz.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 processor,

534 for the ADSP-BF534 processor, and

so on.

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

Page 48

System Services Overview

• _yyy represents the operating environment – This suffix represents the operating environment being targeted such as VDK-based systems, Libraries built for ments, do not include the _yyy suffix.

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

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

• blank – A library without any additional suffix 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.

standalone, specifically non-RTOS environ-

vdk for

linux for Linux-based systems, and so on.

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 targeting silicon revision 0.2 of the ADSP-BF532 processor without any RTOS should link with the

libss1532.dlb file from the Blackfin/lib/bf532_rev_0.2 subdirectory.

As another example, the application developer who wants a version of the System Services Library that will run on any revision of ADSP-BF532 sili con and is using the VDK, should link with the libss1532_vdky.dlb file from the

1-14 VisualDSP++ 4.5 Device Drivers and System

Blackfin/lib directory.

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.

Services Manual for Blackfin Processors

Page 49

Introduction

Debug versions of the libraries can be used by checking the Use Debug System Libraries checkbox on the Link/Processor property page under Project/Options.

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.

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

Blackfin/include/services and blackfin/lib/src/services

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

Page 50

System Services Overview

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

services.h.

3. Define the silicon revision macro, __SILICON_REVISION__, to the proper value. Refer to the description of the in the compiler manual for more information.

4. Compile/assemble all files in the Blackfin/lib/src/services directory.

5. Link the appropriate compiled/assembled objects into a library. Include all object files without any operating environment exten sion (such as VDK) and all object files with the appropriate operating environment extension specific for the environment being targeted (such as

VDK).

Examples

_si_revision switch

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

Dual Core Considerations

For information on how to use the System Services on dual-core ADSP-BF561 processors, see “Dual Core Considerations” on page 3-6.

1-16 VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 51

Introduction

RTOS Considerations

Deployment of System Services and the Device Driver model within an application based around an RTOS, for example VDK, is highly recom mended. However, observe these considerations to avoid conflict with the RTOS and to successfully deploy the Services and Device Drivers within a multi-threaded application.

The following discussion is limited to VDK, but is also relevant in other RTOS environments.

Interoperability of System Services with VDK

There are three major considerations to be borne in mind when deploying System Services and the Device Driver model within a VDK based application.

• Interrupt Handling – A cornerstone of System Services and the Device Driver Model is the interrupt manager. The interrupt manager has been designed to manage only the IVG's that it is requested to manage, as dictated by each call to

adi_int_CECHook(), leaving the other IVG levels to be handled as

per the users' requirements. Thus, VDK managed interrupts can easily coexist alongside those managed by System Services, pro vided that neither method manages the same IVG levels as the

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

Page 52

RTOS Considerations

other. It is not possible to have a VDK ISR and an interrupt manager chain assigned to the same IVG level, as one will overwrite the other in the Event Vector Table (EVT).

All DMA channels and Device Drivers use the default IVG levels as defined in the SIC_IARx registers at the time of device initializa tion (that is, during the call to adi_dev_Open()).

• Prohibited Interrupt Levels – Appendix A of the VisualDSP++ 4.0 Kernel (VDK) User’s Guide details four interrupt levels reserved for exclusive use by VDK and must not be managed by the interrupt manager. These are EVT3 (EVX), EVT6 (IVTMR), IVG14 and IVG15. The latter is also excluded from most VisualDSP++ 4.0 applications as it is used to run the applications in supervisor mode.

• Deferred callbacks - The deferred callback manager offers a similar service to the VDK process running at IVG14. It is highly recom mended that the VDK variant of the System Services Library is used (and indeed the default VDK LDF files ensure its use). This variant essentially passes callbacks posted to the DCB manager to the VDK level 14 process. In this mode of operation, only one call back queue can be used. If the standalone library variant is used then several queues can be managed but none of them must be assigned to the IVG 14 level as this would conflict with the VDK process running at that level.

1-18 VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 53

Introduction

Deployment of Services within a multi-threaded application

Bear these two major considerations in mind when deploying System Services and the Device Driver model within a multi-threaded application.

• Critical regions – System Services and Device Drivers make use of critical regions where atomicity of a code segment is required. These regions are managed via calls to the

adi_int_EnterCriticalRegion/adi_int_ExitCriticalRegion

functions, which are defined in the installation. (For more information, see “Interrupt Manager” in

Chapter 2, Interrupt Manager. It is advised that the above func-

tions are used within threads that make use of System Services rather than the VDK Push/Pop critical region functions.

• Initialization – Initialization of System Services and the Device Manager is only performed once per application. Since their use may be required in several threads it is important that the initializa tion is performed prior to any subsequent use. In addition all Device Drivers that need to adjust their timing values according to the peripheral clock (SCLK) frequency employ a call to

adi_pwr_GetFreq() to determine the frequency (in Hz). The power

adi_int_xxx.c files within the

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

Page 54

Device Driver Overview

management module must be initialized prior to the opening of any device driver. There are basically three approaches that can be adopted:

• Define a function to initialize the System Services and Device Manager and call it from a user-modifiable section of the 'start' routine in

• Assign the initialization to the highest priority boot thread, or

• Use a separate boot thread to perform the initialization and set it at the highest priority and let it either yield to other threads once completed or be destroyed. Please take care to use global and not thread memory to initialize the System Services and Device Man ager in this way.

<Project>_basiccrt.s.

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.

1-20 VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 55

Introduction

The System Services overview covers the following topics:

• “Application Interface” on page 1-21

• “Device Driver Architecture” on page 1-22

• “Initialization” on page 1-24

• “Termination” on page 1-24

• “Device Driver Directory and File Structure” on page 1-25

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. Applications 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 is a model-compliant driver that 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

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

Page 56

Device Driver Overview

• adi_dev_Write() – Provides a device with buffers for outbound data

• adi_dev_Control() – Sets/detects control and status parameters for a device

Like the System Service APIs, the Device Driver API is designed to be called using the standard calling interface of the development toolset’s C run-time model. The Device Driver API can be called by any C or assem bly language program that adheres to the calling conventions and register usage of the C run-time model.

Device Driver 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 application until the oper ation has completed. In asynchronous mode, the API function returns immediately to the application, while the data is moved in the back

ground. It would be wasteful to force each physical driver to provide logic that operates both synchronously and asynchronously. The Device Man

ager provides this functionality, relieving each physical driver from re-implementing this capability.

1-22 VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 57

This architecture is illustrated in Figure 1-2:

APPLICATION

RTOS (OPTIONAL)

DEVICE DRIVER

COMPONENTS

PHYSICAL

DRIVER

DEVICE MANAGER

PHYSICAL

DRIVER

Introduction

PHYSICAL

DRIVER

SYSTEM SERVICES

Figure 1-2. Device Manager Architecture

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 con trol and status register manipulations of the physical device. All device specific information is contained and isolated in the physical driver.

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

Page 58

Device Driver Overview

Interaction with System Services

As shown in Figure 1-2, the Device Driver Model leverages the capabilities 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 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.

adi_dev_Init(), is called by the

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

“Initialization” on page 1-10 for more

information on the initialization of the System Services.

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,

1-24 VisualDSP++ 4.5 Device Drivers and System

adi_dev_Terminate(), is called to

Services Manual for Blackfin Processors

Page 59

Introduction

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.

As part of the termination function processing, the Device Manager closes all open physical drivers. The physical drivers are closed in an abrupt man ner. 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

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.

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

blackfin directory tree.

Page 60

Device Driver Overview

Accessing the Device Driver API

User source files accessing the Device Manager API should include the files

services.h and adi_dev.h, in order, located in the Black-

fin/include/services and Blackfin/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/services.h> // system services #include <drivers/adi_dev.h> // Device Manager #include <drivers/ppi/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. Application 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 Services, 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 Manager (adi_dev.h),

and physical driver include files.

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

1-26 VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 61

Introduction

Application developers using other toolsets should, however, ensure the processor definition macro is appropriately defined. The

services.h file

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

...

The services.h file contains the full and complete list of processor variants 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.

Device Driver File Locations

Device drivers for on-chip peripherals are provided in the libdrvxxx.dlb library for the various processor derivatives, silicon revisions, and so on. Device drivers for off-chip peripherals are not provided within the library, but rather must be included separately with the application. Include files for off-chip peripheral drivers are included in following subdirectories:

$ADI_DSP\Blackfin\include\drivers

where $ADI_DSP is the location of your VisualDSP 4.5 installation, which is, by default, located at:

C:\Program Files\Analog Devices\VisualDSP 4.5

Source files for off-chip peripheral drivers are included in subdirectories:

$ADI_DSP\Blackfin\lib\src\drivers

VisualDSP++ 4.5 Device Drivers and System 1-27 Services Manual for Blackfin Processors

Page 62

Device Driver Overview

When creating applications that include off-chip device drivers, the application should include the .h file for the driver. This is typically done with something like this:

#include <drivers\codec\adi_ad1836.h>

The source code for an off-chip peripheral driver should be included in the source file list of the VisualDSP++ project. For example, if using the AD1836 device driver, the file

$ADI_DSP\Blackfin\lib\src\drivers\codec\adi_ad1836.c

should be included in the source file list.

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

libdrvxxxz.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 processor,

534 for the ADSP-BF534 processor, and

so on.

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

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

• blank – A library without an additional suffix does not contain workarounds to any anomalies.

1-28 VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 63

Introduction

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 targeting silicon revision 0.2 of the ADSP-BF532 processor should link with the

Blackfin/lib/bf532_rev_0.2 subdirectory. As another example, the

application developer who wants a 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.

libdrv532.dlb file from the

Debug versions of the libraries can be used by checking the Use Debug System Libraries checkbox on the Link/Processor property page under Project/Options.

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

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.

VisualDSP++ 4.5 Device Drivers and System 1-29 Services Manual for Blackfin Processors

Page 64

Device Driver Overview

• 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

Blackfin/include/drivers and Blackfin/lib/src/drivers

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

services.h file

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

1-30 VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 65

Introduction

Examples on Distribution

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.

VisualDSP++ 4.5 Device Drivers and System 1-31 Services Manual for Blackfin Processors

Page 66

Device Driver Overview

1-32 VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 67

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

• “Interrupt Manager Initialization” on page 2-4

• “Interrupt Manager Termination” on page 2-5

• “Core Event Controller Functions” on page 2-6

• “System Interrupt Controller Functions” on page 2-9

• “Protecting Critical Code Regions” on page 2-12

• “Modifying IMASK” on page 2-14

• “Examples” on page 2-15

• “File Structure” on page 2-15

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

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

Page 68

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 VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 69

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

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

Page 70

Interrupt Manager 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 manager uses a unique and unambiguous naming convention to guard against conflicts. All enumeration values, typedefs and macros use the

ADI_INT_ prefix, while all functions within the interrupt manager use the 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.

Interrupt Manager 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 inter rupt handler that is hooked into an IVG level to be the primary interrupt handler. Any additional interrupt handlers that hooked into that same IVG level are considered secondary handlers. Without any additional memory from the application, the interrupt manager can support one pri mary 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, then

2-4 VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 71

Interrupt Manager

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 addi

tional memory to support the secondary handlers.

The ADI_INT_SECONDARY_MEMORY macro is defined to be the amount of memory, in bytes, that is required to support a single secondary handler. Therefore, the application should provide to the initialization function “

n” times ADI_INT_SECONDARY_MEMORY, where “n” is the number of second-

ary 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 structures 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.

Interrupt Manager Termination

When the functionality of the interrupt manager is no longer required, the application can call the termination function of the interrupt manager,

adi_int_Terminate(). 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 controlling. 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

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

Page 72

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_CECUnhook() Function functions.

adi_int_CECHook() Function

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.

adi_int_CECHook() Function and

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

ADI_INT_RESULT_PROCESSED or ADI_INT_RESULT_NOT_PROCESSED return

code.

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

2-6 VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 73

Interrupt Manager

interrupt is not the event the interrupt handler was expecting, it should immediately return with the

ADI_INT_RESULT_NOT_PROCESSED return code.

The interrupt manager then automatically invokes the next interrupt han dler, 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 should return the

ADI_INT_RESULT_PROCESSED return code.

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 arlibdrvxxxz.dlbe hooked into that same IVG chain are called secondary handlers. When the primary handler is hooked into the chain, the interrupt 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 interrupt 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

gered, after calling the primary handler (and assuming the primary

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

Page 74

Core Event Controller Functions

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() Function

The adi_int_CECUnhook() function is used to unhook an interrupt handler 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 dlers are in fact nothing more than typical C-callable subroutines.

Each peripheral interrupt handler must, therefore, conform to the following template,

ADI_INT_HANDLER(mjk_SPORT_RX_handler) {

2-8 VisualDSP++ 4.5 Device Drivers and System

RTI instruction on completion.

RTS return function. Interrupt han-

Services Manual for Blackfin Processors

Page 75

Interrupt Manager

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

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

ADI_INT_PERIPHERAL_ID identifies each possible peripheral interrupt

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

Page 76

System Interrupt Controller Functions

source for the processor. This enumeration is defined in the adi_int.h file. Refer to this header file for the complete list of values for each sup ported Blackfin processor.

adi_int_SICDisable()

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

IMASK register to disable the given

adi_int_SICEnable()

The adi_int_SICEnable() function is used to enable a peripheral interrupt to be passed to the Core Event Controller. When called, this function programs the appropriate SIC interrupt.

IMASK register to enable the given peripheral

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 ADI_INT_PERIPHERAL_ID parameter, this function is passed pointer-to-memory location information. The function interro gates 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.

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

2-10 VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 77

Interrupt Manager

application’s interrupt handlers to determine if a given peripheral interrupt 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 function 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 power-up, the Blackfin processor invokes a default mapping of peripheral interrupts to IVG level. This function alters that mapping. In addition to the 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_PERIPHERAL_ID

adi_int_SICWakeup()

The adi_int_SICWakeup() function is used to enable or disable a peripheral 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 periph eral interrupt wakes up the core when the interrupt is triggered. 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.

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

ADI_INT_PERIPHERAL_ID

Page 78

Protecting Critical Code Regions

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 Code 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() and adi_int_ExitCriticalRegion(). The application calls the beginning of the critical section of code, and then calls the

adi_int_ExitCriticalRegion() function at the end of the critical section.

These functions should always be used in pairs.

adi_int_EnterCriticalRegion() function at the

The actual implementation of these functions varies from operating environment 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.

The adi_int_EnterCriticalRegion() function is passed an argument of type

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

returned from the adi_int_EnterCriticalRegion() function must always be passed to the corresponding

adi_int_ExitCriticalRegion() function.

For example, examine the following code sequence:

2-12 VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 79

Interrupt Manager

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

adi_int_ExitCriticalRegion() function. While nesting of calls to these

functions is allowed, the application developer minimizes the use of these functions to only those critical sections of code, and realize that in all like lihood 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 of code. The function

... 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); … // critical section of code adi_int_ExitCriticalRegion(Value); ... }

Foo() also has a critical region of code.

Foo() while in a critical section

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

Page 80

Modifying IMASK

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.

All system services and device drivers use these functions exclusively 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 ister to be set or cleared. Depending on the operating environment, these function may modify the

IMASK manipulation functions. Regardless of how the IMASK value is

changed, the interrupt manager API provides a uniform and consistent mechanism for this.

IMASK value directly, or use the RTOS provided

IMASK reg-

Two operating environment implementation dependent functions are provided to set and clear bits in the IMASK register. These functions are

adi_int_SetIMASKBits and adi_int_ClearIMASKBits. These functions

2-14 VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 81

Interrupt Manager

take as a parameter a value that corresponds to the IMASK register of the processor being targeted. When the called, the function sets to 1 those bits in 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 individual 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.

File Structure

The API for the interrupt manager is defined in the adi_int.h header file. This file is located in the automatically included by the services.h file in that same directory. Only the

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

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

Blackfin/include/services subdirectory and is

Page 82

File Structure

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-2 in Chapter 6, DMA

Blackfin/lib directory. See the

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

di_int_xxx.c where xxx is the oper-

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.

2-16 VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 83

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

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

Page 84

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_Init( 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 VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 85

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 Interrupt Vector Groups that were enabled and controlled by the interrupt manager are disabled.

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

adi_int_Terminate().

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

Page 86

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 VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 87

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.

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

Page 88

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, void *ClientArg );

2-22 VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 89

Interrupt Manager

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.

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

To remove the interrupt handler successfully, match this value to the

adi_int_CECHook() function when the interrupt

the handler was hooked into the chain.

ClientArg parameter that was passed to

Return Value

Return values include:

ADI_INT_RESULT_SUCCESS The interrupt handler was successfully unhooked from

the chain.

ADI_INT_RESULT_INVALID_IVG The IVG level is invalid.

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

Page 90

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 environment. In the standalone version of the service, this function detects if the processor is within a protected region of code (refer to the functions

adi_int_EnterCriticalRegion and adi_int_ExitCriticalRegion, respec-

tively). 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_ExitCriticalRegion function is called, the saved

IMASK value with the new bit settings, is restored. If upon entering

this function, the processor is not within a protected region of code, the “live”

IMASK register is updated accordingly.

Information on the implementation details for this function in other operating environments can be found in the file adi_int_xxx.h, located in the

Blackfin/include/services/ directory, where xxx is the operating

environment.

Note that regardless of the implementation details, the API is consistent from environment to operating environment. Changes to application soft ware are not required when code is moved to a different operating environment.

Prototype

void adi_int_ClearIMASKBits( ADI_INT_IMASK BitsToClear );

2-24 VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 91

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

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

Page 92

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 environment. In the standalone version of the service, this function effectively disables interrupts, saving the current value of IMASK to a temporary location. 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 levels. In the standalone version, the pArg parameter to the

adi_int_EnterCriticalRegion is meaningless.

Information on the implementation details for this function in other operating 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 VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 93

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 corresponding adi_int_ExitCriticalRegion function.

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

Page 94

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 VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 95

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

figured.

ADI_INT_RESULT_INVALID_PERI PHERALID

The peripheral ID specified is invalid.

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

Page 96

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

figured.

ADI_INT_RESULT_INVALID_PERI PHERAL_ID

The peripheral ID specified is invalid.

2-30 VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 97

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 possible return values include:

ADI_INT_RESULT_INVALID_PERI PHERAL_ID

ADI_INT_RESULT_INVALID_IVG The interrupt vector group level is invalid.

The peripheral ID specified is invalid.

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

Page 98

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_PERI PHERAL_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 VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors

Page 99

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 possible return values include:

ADI_INT_RESULT_INVALID_PERI PHERAL_ID

ADI_INT_RESULT_INVALID_IVG The interrupt vector group level is invalid.

The peripheral ID specified is invalid.

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

Page 100

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

adi_int_EnterCriticalRegion and adi_int_ExitCriticalRegion func-

tions). 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_ExitCriticalRegion function is called, the saved IMASK value,

with the new bit settings, is restored. If upon entering this function the processor is not within a protected region of code, the “live”

IMASK register

is updated accordingly.

Information on the implementation details for this function in other operating 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 VisualDSP++ 4.5 Device Drivers and System

Services Manual for Blackfin Processors