edk libs ref guide

160
R EDK OS and Libraries Reference Guide Embedded Development Kit EDK 6.2i UG114 (v3.0) June 22, 2004

Upload: tcthamy

Post on 18-Nov-2014

130 views

Category:

Documents


5 download

DESCRIPTION

use edk of xilinx

TRANSCRIPT

Page 1: Edk Libs Ref Guide

R

EDK OS and Libraries Reference Guide

Embedded Development KitEDK 6.2i

UG114 (v3.0) June 22, 2004

Page 2: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com UG114 (v3.0) June 22, 20041-800-255-7778

"Xilinx" and the Xilinx logo shown above are registered trademarks of Xilinx, Inc. Any rights not expressly granted herein are reserved.

CoolRunner, RocketChips, Rocket IP, Spartan, StateBENCH, StateCAD, Virtex, XACT, XC2064, XC3090, XC4005, and XC5210 are registered trademarks of Xilinx, Inc.

The shadow X shown above is a trademark of Xilinx, Inc.

ACE Controller, ACE Flash, A.K.A. Speed, Alliance Series, AllianceCORE, Bencher, ChipScope, Configurable Logic Cell, CORE Generator, CoreLINX, Dual Block, EZTag, Fast CLK, Fast CONNECT, Fast FLASH, FastMap, Fast Zero Power, Foundation, Gigabit Speeds...and Beyond!, HardWire, HDL Bencher, IRL, J Drive, JBits, LCA, LogiBLOX, Logic Cell, LogiCORE, LogicProfessor, MicroBlaze, MicroVia, MultiLINX, NanoBlaze, PicoBlaze, PLUSASM, PowerGuide, PowerMaze, QPro, Real-PCI, RocketIO, SelectIO, SelectRAM, SelectRAM+, Silicon Xpresso, Smartguide, Smart-IP, SmartSearch, SMARTswitch, System ACE, Testbench In A Minute, TrueMap, UIM, VectorMaze, VersaBlock, VersaRing, Virtex-II Pro, Virtex-II EasyPath, Wave Table, WebFITTER, WebPACK, WebPOWERED, XABEL, XACT-Floorplanner, XACT-Performance, XACTstep Advanced, XACTstep Foundry, XAM, XAPP, X-BLOX +, XC designated products, XChecker, XDM, XEPLD, Xilinx Foundation Series, Xilinx XDTV, Xinfo, XSI, XtremeDSP and ZERO+ are trademarks of Xilinx, Inc.

The Programmable Logic Company is a service mark of Xilinx, Inc.

All other trademarks are the property of their respective owners.

Xilinx, Inc. does not assume any liability arising out of the application or use of any product described or shown herein; nor does it convey any license under its patents, copyrights, or maskwork rights or any rights of others. Xilinx, Inc. reserves the right to make changes, at any time, in order to improve reliability, function or design and to supply the best product possible. Xilinx, Inc. will not assume responsibility for the use of any circuitry described herein other than circuitry entirely embodied in its products. Xilinx provides any design, code, or information shown or described herein "as is." By providing the design, code, or information as one possible implementation of a feature, application, or standard, Xilinx makes no representation that such implementation is free from any claims of infringement. You are responsible for obtaining any rights you may require for your implementation. Xilinx expressly disclaims any warranty whatsoever with respect to the adequacy of any such implementation, including but not limited to any warranties or representations that the implementation is free from claims of infringement, as well as any implied warranties of merchantability or fitness for a particular purpose. Xilinx, Inc. devices and products are protected under U.S. Patents. Other U.S. and foreign patents pending. Xilinx, Inc. does not represent that devices shown or products described herein are free from patent infringement or from any other third party right. Xilinx, Inc. assumes no obligation to correct any errors contained herein or to advise any user of this text of any correction if such be made. Xilinx, Inc. will not assume any liability for the accuracy or correctness of any engineering or software support or assistance provided to a user.

Xilinx products are not intended for use in life support appliances, devices, or systems. Use of a Xilinx product in such applications without the written consent of the appropriate Xilinx officer is prohibited.

The contents of this manual are owned and copyrighted by Xilinx. Copyright 1994-2004 Xilinx, Inc. All Rights Reserved. Except as stated herein, none of the material may be copied, reproduced, distributed, republished, downloaded, displayed, posted, or transmitted in any form or by any means including, but not limited to, electronic, mechanical, photocopying, recording, or otherwise, without the prior written consent of Xilinx. Any unauthorized use of any material contained in this manual may violate copyright laws, trademark laws, the laws of privacy and publicity, and communications regulations and statutes.

R

Page 3: Edk Libs Ref Guide

UG114 (v3.0) June 22, 2004 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778

EDK OS and Libraries Reference Guide UG114 (v3.0) June 22, 2004

The following table shows the revision history for this document.

Version Revision

01/30/04 1.0 Initial release for EDK 6.2i.

03/12/04 Updated for service pack release.

03/19/04 2.0 Updated for service pack release.

06/22/04 3.0 Updated for service pack release.

Page 4: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com UG114 (v3.0) June 22, 20041-800-255-7778

Page 5: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 5UG114 (v3.0) June 22, 2004 1-800-255-7778

R

Preface

About This Guide

This book describes the software packages provided by the Embedded Development Kit (EDK).

Guide ContentsThis book contains the following chapters.

� Chapter 1, “Introduction”

� Chapter 2, “Xilinx Microkernel (XMK)”

� Chapter 3, “LibXil Standard C Libraries”

� Chapter 4, “Standalone Board Support Package”

� Chapter 5, “Xilkernel”

� Chapter 6, “LibXil Net”

� Chapter 7, “LibXil File”

� Chapter 8, “LibXil FATFile System (FATfs)”

� Chapter 9, “LibXil Memory File System (MFS)”

� Chapter 10, “LibXil Profile”

Additional ResourcesFor additional information, go to http://support.xilinx.com. The following table lists some of the resources you can access from this website. You can also directly access these resources using the provided URLs.

Resource Description/URL

EDK Home Embedded Development Kit home page, FAQ and tips.

http://www.xilinx.com/edk

EDK Examples A set of complete EDK examples.

http://www.xilinx.com/ise/embedded/edk_examples.htm

Tutorials Tutorials covering Xilinx design flows, from design entry to verification and debugging

http://support.xilinx.com/support/techsup/tutorials/index.htm

Answer Browser Database of Xilinx solution records

http://support.xilinx.com/xlnx/xil_ans_browser.jsp

Page 6: Edk Libs Ref Guide

6 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Preface: About This GuideR

ConventionsThis document uses the following conventions. An example illustrates each convention.

TypographicalThe following typographical conventions are used in this document:

Application Notes Descriptions of device-specific design techniques and approaches

http://support.xilinx.com/apps/appsweb.htm

Data Sheets Device-specific information on Xilinx device characteristics, including readback, boundary scan, configuration, length count, and debugging

http://support.xilinx.com/xlnx/xweb/xil_publications_index.jsp

Problem Solvers Interactive tools that allow you to troubleshoot your design issues

http://support.xilinx.com/support/troubleshoot/psolvers.htm

Tech Tips Latest news, design tips, and patch information for the Xilinx design environment

http://www.support.xilinx.com/xlnx/xil_tt_home.jsp

GNU Manuals The entire set of GNU manuals

http://www.gnu.org/manual

Resource Description/URL

Convention Meaning or Use Example

Courier fontMessages, prompts, and program files that the system displays

speed grade: - 100

Courier boldLiteral commands that you enter in a syntactical statement ngdbuild design_name

Helvetica bold

Commands that you select from a menu File � Open

Keyboard shortcuts Ctrl+C

Italic font

Variables in a syntax statement for which you must supply values

ngdbuild design_name

References to other manualsSee the Development System Reference Guide for more information.

Emphasis in textIf a wire is drawn so that it overlaps the pin of a symbol, the two nets are not connected.

Page 7: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 7UG114 (v3.0) June 22, 2004 1-800-255-7778

ConventionsR

Online DocumentThe following conventions are used in this document:

Square brackets [ ]

An optional entry or parameter. However, in bus specifications, such as bus[7:0], they are required.

ngdbuild [option_name] design_name

Braces { } A list of items from which you must choose one or more lowpwr ={on|off}

Vertical bar | Separates items in a list of choices lowpwr ={on|off}

Vertical ellipsis...

Repetitive material that has been omitted

IOB #1: Name = QOUT’ IOB #2: Name = CLKIN’...

Horizontal ellipsis . . . Repetitive material that has been omitted

allow block block_name loc1 loc2 ... locn;

Convention Meaning or Use Example

Convention Meaning or Use Example

Blue textCross-reference link to a location in the current document

See the section “Additional Resources” for details.

Refer to “Title Formats” in Chapter 1 for details.

Red text Cross-reference link to a location in another document

See Figure 2-5 in the Virtex-II Handbook.

Blue, underlined text Hyperlink to a website (URL) Go to http://www.xilinx.com for the latest speed files.

Page 8: Edk Libs Ref Guide

8 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Preface: About This GuideR

Page 9: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 9UG114 (v3.0) June 22, 2004 1-800-255-7778

Preface: About This GuideGuide Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Additional Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Typographical . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Online Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Chapter 1: Introduction

Chapter 2: Xilinx Microkernel (XMK)Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17XMK Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Chapter 3: LibXil Standard C LibrariesOverview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Standard C Library (libc.a) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Xilinx C Library (libxil.a) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Input/Output Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Memory Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

MicroBlaze Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23PowerPC 405 Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Arithmetic Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23MicroBlaze Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Integer Arithmetic. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Floating Point Arithmetic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

PowerPC 405 Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Integer Arithmetic. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Floating Point Arithmetic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Chapter 4: Standalone Board Support PackageMicroBlaze BSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Interrupt Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25void microblaze_enable_interrupts(void). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25void microblaze_disable_interrupts(void) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Instruction Cache Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25void microblaze_enable_icache(void) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25void microblaze_disable_icache(void) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26void microblaze_update_icache (int tag, int instr, int lock_valid) . . . . . . . . . . . . . . . . . 26void microblaze_init_icache_range (int cache_addr, int cache_size) . . . . . . . . . . . . . . . 26

Data Cache Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26void microblaze_enable_dcache(void) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26void microblaze_disable_dcache(void). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Table of Contents

Page 10: Edk Libs Ref Guide

10 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

R

void microblaze_update_dcache (int tag, int data, int lock_valid) . . . . . . . . . . . . . . . . . 27void microblaze_init_dcache_range (int cache_addr, int cache_size) . . . . . . . . . . . . . . . 27

Fast Simplex Link Interface Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27microblaze_bread_datafsl(val, id). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27microblaze_bwrite_datafsl(val, id) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27microblaze_nbread_datafsl(val, id). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27microblaze_nbwrite_datafsl(val, id) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27microblaze_bread_cntlfsl(val, id) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27microblaze_bwrite_cntlfsl(val, id). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27microblaze_nbread_cntlfsl(val, id) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28microblaze_nbwrite_cntlfsl(val, id) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

PowerPC BSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Boot Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

boot.S . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28crt0.S . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28eabi.S. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28void XCache_WriteCCR0(unsigned int val);. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29void XCache_EnableDCache(unsigned int regions);. . . . . . . . . . . . . . . . . . . . . . . . . . . . 29void XCache_DisableDCache(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29void XCache_FlushDCacheLine(unsigned int adr); . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29void XCache_StoreDCacheLine(unsigned int adr);. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29void XCache_EnableICache(unsigned int regions); . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29void XCache_DisableICache(void);. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29void XCache_InvalidateICache(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30void XCache_InvalidateICacheLine(unsigned int adr); . . . . . . . . . . . . . . . . . . . . . . . . . 30

Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30void XExc_Init(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30void XExc_RegisterHandler(Xuint8 ExceptionId, XExceptionHandler Handler, void *DataPtr);31void XExc_RemoveHandler(Xuint8 ExceptionId). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32void XExc_mEnableExceptions (EnableMask); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32void XExc_mDisableExceptions (DisableMask);. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32int read(int fd, char *buf, int nbytes); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32int write(int fd, char *buf, int nbytes);. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32int isatty(int fd); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33char *sbrk(int nbytes); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Processor-Specific Include Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

typedef unsigned long long XTime; . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33void XTime_SetTime(XTime xtime); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33void XTime_GetTime(XTime *xtime);. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33void XTime_TSRClearStatusBits(unsigned long Bitmask); . . . . . . . . . . . . . . . . . . . . . . . 33void XTime_PITSetInterval(unsigned long interval); . . . . . . . . . . . . . . . . . . . . . . . . . . . 34void XTime_PITEnableInterrupt(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34void XTime_PITDisableInterrupt(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35void XTime_PITEnableAutoReload(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35void XTime_PITDisableAutoReload(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35void XTime_PITClearInterrupt(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35unsigned int usleep(unsigned int __useconds); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35unsigned int sleep(unsigned int __seconds); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Page 11: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 11UG114 (v3.0) June 22, 2004 1-800-255-7778

R

int nanosleep(const struct timespec *rqtp, struct timespec *rmtp); . . . . . . . . . . . . . . . . . 36

Chapter 5: XilkernelOverview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Key Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Xilkernel Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Xilkernel Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Building Xilkernel Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Xilkernel Process Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Xilkernel Scheduling Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Xilkernel API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Process Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Thread Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Semaphores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50Message Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55Shared Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Mutex Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Dynamic Block Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Interrupt Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Kernel Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Customizing STDIN and STDOUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71Customizing User Initialization Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71Customizing Process Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Customizing Scheduling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Customizing Thread Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Customizing Semaphore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Customizing Message Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Customizing Shared Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Customizing Pthread Mutex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Customizing Dynamic Block Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Customizing Linker Script (PPC405) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Configuring System Timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77Configuring Interrupt Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77Configuring Debug Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77Copy Kernel Source Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Debugging Xilkernel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78Memory Footprint. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78Xilkernel File Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79System Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Future Enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Modifying Xilkernel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80User Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Chapter 6: LibXil NetOverview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83LibXilNet Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Page 12: Edk Libs Ref Guide

12 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

R

Quick Glance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Protocols Supported. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Library Architecture. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Protocol Function Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Media Access Layer (MAC) Drivers Wrapper. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87Ethernet Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87ARP (RFC 826) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87IP (RFC 791) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87ICMP (RFC 792) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87UDP (RFC 768) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87TCP (RFC 793) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88Sockets API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88Buffer Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Current Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88Functions of LibXilNet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88LibGen Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Using XilNet in Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Chapter 7: LibXil FileOverview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Module Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Module Routines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Libgen Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

LibXil File Instantiation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104System Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Chapter 8: LibXil FATFile System (FATfs)Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107XilFatfs Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

Detailed Description of XilFatfsFunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108LibGen Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

Chapter 9: LibXil Memory File System (MFS)Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113MFS Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Quick Glance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113Detailed summary of MFS Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

Utility Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120Additional Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121C-like access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121LibGen Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Chapter 10: LibXil ProfileOverview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Page 13: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 13UG114 (v3.0) June 22, 2004 1-800-255-7778

R

Features. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123Profiling Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124Customizing xilprofile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124Building Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

Application Memory Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125Generating GPROF Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125XilProfile Code Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Chapter 11: lwIP LibraryOverview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129PowerPC System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129MicroBlaze System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Setting Up lwIP in EDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

libgen Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132Designing an lwIP Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Initializing lwIP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133lwIP Raw API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

Raw APO Functions for TCP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134Example lwIP Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

PowerPC based Echo Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135C Program. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

MicroBlaze-Based Echo Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150C Program. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

Page 14: Edk Libs Ref Guide

14 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

R

Page 15: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 15UG114 (v3.0) June 22, 2004 1-800-255-7778

R

Chapter 1

Introduction

This book describes the software packages that are provided by the EmbeddedDevelopment Kit. EDK supplies libraries, board support packages, and completeoperating systems, in addition to the drivers for the peripherals, to help the user develop asoftware platform. The following is the distribution of the software packages available forthe user to include in his platform:

� Xilinx Micro-Kernel (XMK) - XMK is the entity representing the collective software system formed by the following components,

� Standard C Libraries (libc, libm)

� Xilkernel - An embedded kernel

� Standalone Board Support Package (BSP)

� LibXil Net - A networking library

� LibXil MFS - A Memory File System

� LibXil File - A file I/O library

� LibXil Drivers - Device drivers for supported peripherals

� VxWorks Operating System

The software platform can be defined using XPS’s Software Platform Settings dialog box.Figure 1-1 shows a snapshot of the dialog box. In this example, the user is choosing theXilnet and Xilfile libraries, along with the Xilkernel operating system.

This guide documents the Xilinx Micro-kernel, its constituent libraries and the Standaloneboard-support package. Documentation for the other operating systems can be found intheir respective reference guides. Device drivers are documented along with thecorresponding peripheral’s documentation.

Page 16: Edk Libs Ref Guide

16 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 1: IntroductionR

Figure 1-1: Software Platform Settings in XPS

Page 17: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 17UG114 (v3.0) June 22, 2004 1-800-255-7778

R

Chapter 2

Xilinx Microkernel (XMK)

This chapter describes the organization of Xilinx Microkernel, its constituent component libraries and the interactions between them and the user application.

The chapter contains the following sections.

� “Overview”

� “XMK Organization”

OverviewThere are three distinct software entities in XMK, with which user applications can interface - Standard C and Math libraries, LibXil libraries and Xilkernel or Standalone operating systems.

The Standard C support library consists of the newlib libc, which contains the standard C functions such as stdio, stdlib and string routines. The math library is an enhancement over the newlib math library libm and provides the standard math routines.

The LibXil libraries consist of,

� LibXil Driver - Xilinx device drivers

� LibXil Net - Xilinx networking support

� LibXil File - Xilinx file I/O functions

� LibXil MFS - Xilinx memory file system

� LibXil Profile - Xilinx profiling support

The Xilinx Standalone Board Support Package (BSP) and Xilkernel are the two operating system choices that are provided, in XMK, that can be included in the user application’s software platform.

Most of the routines in the library are written in C and can be ported to any platform. The Library Generator (LibGen) configures the libraries for an embedded processor, using the attributes defined in the Microprocessor Software Specification (MSS) file.

XMK OrganizationThe structure of XMK is outlined in Figure 2-1. As shown in the figure, the user application can interface with the XMK components in a variety of ways. The libraries are independent of each other, except for a few interactions and dependencies between each other. For example, Xilkernel internally uses the standalone BSP and LibXil File can optionally work with the LibXil MFS. The LibXil Drivers and the standalone BSP form the lowermost hardware abstraction layer. All the library and OS components of XMK rely on standard C library components. The math library, libm.a is also available for linking with the user

Page 18: Edk Libs Ref Guide

18 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 2: Xilinx Microkernel (XMK)R

applications. Users can mix and match the component libraries, but there may be some restrictions and implications. This will be described in the reference guides of each component.

The Standalone Board Support Package (BSP) is a bare-bones kernel. It provides a very thin interface to the hardware, offering minimal functionality that will be required by applications. Some typical functions offered by the standalone BSP include setting up the interrupt system, exception system, configuring caches and other hardware specific functions. Certain standalone board support files such as the crt0.S, boot.S and eabi.S are required for the powerpc processor. These files are provided in the EDK. For a detailed description, refer to Chapter 4, “Standalone Board Support Package.”

LibXil Driver refers to the device drivers that are included in the software platform to provide an interface to the peripherals in the system. These drivers are provided along with EDK and are configured by libgen. This book contains a chapter that briefly discusses the concept of device drivers and the way they fit in with the software platform, in EDK. Refer to the “Device Drivers Programmer Guide” chapter in the Processor IP Reference Guide for this documentation. Device Drivers are documented in further detail, with information about functionality, interface, configuration and headers file information, in the Xilinx Device Drivers Reference Guide.

Xilkernel(1) is a simple embedded processor kernel, which can be customized to a great degree for a given system. Xilkernel has the key features of an embedded kernel like multi-tasking, priority-driven preemptive scheduling, inter-process communication, synchronization facilities, interrupt handling etc. It is small, modular, user customizable and can be used in different system configurations. It is different from the other libraries, (as indicated in Figure 2-1 in that, it can be in a separate executable file from the user application. The user application can dynamically link with Xilkernel through a system call interface. Applications can also statically link with Xilkernel, in a different mode, and form a single executable. Complete details are available in Chapter 5, “Xilkernel.”

LibXil Net provides networking support using a simple TCP/IP stack based library, which can be used for network related projects. For complete details, refer to Chapter 6, “LibXil Net.”

Figure 2-1: XMK Structure

1. Previous EDK releases supported the library version of Xilkernel, which is now deprecated. Refer to Chapter 5, “Xilkernel” for documentation on LibXilkernel.

libc

libm

Standalone BSP

Xil Kernel LibXil Net LibXil FileLibXilProfileLibXil Mfs

LibXil Driver

stdio

stdlib

string

Other

X10143

User Application

Hardware

Page 19: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 19UG114 (v3.0) June 22, 2004 1-800-255-7778

XMK OrganizationR

LibXil File provides stream based file system and device access through interfaces such as open, close, read and write. The standard newlib libc contains dummy functions for most of the operating system specific function calls such as open, close, read, write. These routines are included in the libgloss component of the standard libc library. The LibXil File module contains routines to overwrite these dummy functions. The routines interact with file systems such as Xilinx Memory File System and peripheral devices such as UART, UARTLITE and GPIO. For complete details refer to Chapter 7, “LibXil File.”

LibXil MFS provides a simple memory based file system, which allows easy access to data using file based input-output. This system can be easily configured to meet project requirements by changing the source provided in the installation area. This module is discussed in detail in Chapter 9, “LibXil Memory File System (MFS).”

LibXil Profile provides a mechanism to perform call-graph and histogram profiling and produces the profile data in a format that can be analyzed using GNU gprof. For details refer to Chapter 10, “LibXil Profile.”

User applications will need to include appropriate headers and link with required libraries for proper compilation and inclusion of required functionality. These libraries and their corresponding include files are created in the processor’s lib and include directories, under the current project, respectively. The -I and -L options of the compiler being used should be leveraged to add these directories to the search paths. Libgen is used to tailor the compilation of each software component described above. Refer to the chapters on Libgen and Microprocessor Software Specification in the Embedded Systems Tools Reference Guide for more information.

Page 20: Edk Libs Ref Guide

20 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 2: Xilinx Microkernel (XMK)R

Page 21: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 21UG114 (v3.0) June 22, 2004 1-800-255-7778

R

Chapter 3

LibXil Standard C Libraries

This chapter describes the software libraries available for the embedded processors. The chapter contains the following sections.

� “Overview”

� “Standard C Library (libc.a)”

� “Xilinx C Library (libxil.a)”

� “Input/Output Functions”

� “Memory Management Functions”

� “Arithmetic Operations”

OverviewThe Embedded Processor Design Kit (EDK) libraries and device drivers provide standard C library functions, as well as functions to access peripherals. The EDK libraries are automatically configured by libgen for every project based upon the Microprocessor Software Specification file. These libraries and include files are saved in the current project’s lib and include directories respectively. The -I and -L options of mb-gcc should be used to add these directories to its library search paths.

Standard C Library (libc.a) The standard C library libc.a contains the standard C functions compiled for MicroBlaze or PowerPC. For a list of all the supported functions refer to the following files in XILINX_EDK/gnu/processor/platform/include

where

� processor = powerpc-eabi or microblaze

� platform = sol, nt or lin

� XILINX_EDK = Installation directory

_ansi.h fastmath.h machine/ reent.h stdlib.h utime.h _syslist.h fcntl.h malloc.h regdef.h string.h utmp.h ar.h float.h math.h setjmp.h sys/ assert.h grp.h paths.h signal.h termios.h ctype.h ieeefp.h process.h stdarg.h time.h dirent.h limits.h pthread.h stddef.h unctrl.h errno.h locale.h pwd.h stdio.h unistd.h

Page 22: Edk Libs Ref Guide

22 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 3: LibXil Standard C LibrariesR

Programs accessing standard C library functions must be compiled as follows:

For MicroBlaze

mb-gcc C files

For PowerPC

powerpc-eabi-gcc C files

The libc library is included automatically.

The -lm option should be specified for programs that access libm math functions.

Refer to “MicroBlaze Application Binary Interface,” (ABI) in the MicroBlaze Processor Reference Guide for information on the C Runtime Library

Xilinx C Library (libxil.a)The Xilinx C library libxil.a contains the following functions for the MicroBlaze embedded processor:

_exception_handler.o_interrupt_handler.o_program_clean.o_program_init.oxil_malloc.oxil_sbrk.o

Default exception and interrupt handlers are provided. A memory management targeted for embedded systems is provided in the xil_malloc.o file. The libxil.a library is included automatically.

Programs accessing Xilinx C library functions must be compiled as follows:

mb-gcc C files

Input/Output FunctionsThe EDK libraries contains standard C functions for I/O, such as printf and scanf. These are large and may not be suitable for embedded processors. In addition, the EDK processors (MicroBlaze and PowerPC405) library provides the following smaller I/O functions:

void print (char *)

This function prints a string to the peripheral designated as standard output in the MSS file. This function outputs the passed string as is and there is no interpretation of the string passed. For example, a “\n” passed is interpreted as a new line character and not as a carriage return and a new line as is the case with ANSI C printf function.

void putnum (int)

This function converts an integer to a hexadecimal string and prints it to the peripheral designated as standard output in the MSS file.

void xil_printf (const *char ctrl1, ...)

This function is similar to printf but much smaller in size (only 1KB). It does not have support for floating point numbers. xil_printf also does not support printing of long long (i.e 64 bit numbers).

The prototypes for these functions are in stdio.h.

Page 23: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 23UG114 (v3.0) June 22, 2004 1-800-255-7778

Memory Management FunctionsR

Please refer to the “Microprocessor Software Specification (MSS)” chapter in the Embedded System Tools Guide for information on setting the standard input and standard output devices for a system.

Memory Management Functions

MicroBlaze ProcessorMemory management routines such as malloc, calloc and free can run the gamut of high functionality (with associated large size) to low functionality (and small size). By default, the MicroBlaze processor library only supports a simple, small malloc, and a dummy free. Hence when memory is allocated using malloc, this memory cannot be reused.

In addition to the simple version, we have now extended the standalone BSP to includexil_malloc, xil_free and xil_calloc function. In the Standalone OS block, if thePARAMETER need_xil_malloc is set to TRUE, calls to malloc result in a call toxil_malloc and the same for free and calloc. These functions are a lighter version of thenewlib based malloc and free, but have the same functionality.

The _STACK_SIZE option to mb-gcc specifies the total memory allocated to stack and heap. The stack is used for function calls, register saves, and local variables. All calls to malloc allocate memory from heap. The stack pointer initially points to the bottom (high end) of memory, and grows toward low memory; the heap pointer starts at low memory and grows toward high memory. The size of the heap cannot be increased at runtime. The return value of malloc must always be checked to ensure that it could actually allocate the memory requested.

Please note that whereas malloc checks that the memory it allocates does not overwrite the current stack pointer, updates to the stack pointer do not check if the heap is being overwritten.

Increasing the _STACK_SIZE may be one way to solve unexpected program behavior. Refer to “Linker Options” in the “GNU Compiler Tools” chapter of the Embedded System Tools Guide for more information on increasing the stack size.

PowerPC 405 ProcessorPowerPC 405 processor supports all standard C library memory management functions such as malloc(), calloc(), free().Similar to MicroBlaze, the lighter version of malloc and free i.e xil_malloc and xil_free can be used for PowerPC when the standalone BSP package is used.

Arithmetic Operations

MicroBlaze Processor

Integer Arithmetic

Integer addition and subtraction operations are provided in hardware. By default, integer multiplication is done in software using the library function mulsi3_proc. Integer multiplication is done in hardware if the mb-gcc option -mno-xl-soft-mul is specified.

Page 24: Edk Libs Ref Guide

24 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 3: LibXil Standard C LibrariesR

Integer divide and mod operations are done in software using the library functions divsi3_proc and modsi3_proc. MicroBlaze processor can also be customized to use a hard divider, in which case the div instruction is used in place of the divsi3_proc library routine.

Double precision multiplication, division and mod functions are carried out by the library functions muldi3_proc, divdi3_proc and moddi3_proc respectively.

Floating Point Arithmetic

All floating point addition, subtraction, multiplication and division operations are also implemented using software functions in the C library.

PowerPC 405 Processor

Integer Arithmetic

Integer addition and subtraction operations are provided in hardware. Hence no specific software library is available for the PowerPC processor.

Floating Point Arithmetic

The PowerPC processor supports all floating point arithmetic implemented in the standard C library.

Page 25: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 25UG114 (v3.0) June 22, 2004 1-800-255-7778

R

Chapter 4

Standalone Board Support Package

The Board Support Package (BSP) is a set of software modules used to access processor specific functions. The standalone BSP is used when an application accesses board/processor features directly (without an intervening Operating System layer).

This chapter contains the following sections.

� “MicroBlaze BSP”

� “PowerPC BSP”

MicroBlaze BSPWhen the user system contains a MicroBlaze processor and no Operating System, the Library Generator automatically builds the standalone BSP in the project library libxil.a.

Interrupt HandlingThe microblaze_enable_interrupts.s and microblaze_disable_interrupts.s files contain functions to enable and disable interrupts on the MicroBlaze.

void microblaze_enable_interrupts(void)

This function enables interrupts on the MicroBlaze. When the MicroBlaze starts up, interrupts are disabled. Interrupts must be explicitly turned on using this function.

void microblaze_disable_interrupts(void)

This function disables interrupts on the MicroBlaze. This function may be called when entering a critical section of code where a context switch is undesirable.

Instruction Cache HandlingThe microblaze_enable_icache.s and microblaze_disable_icache.s files contain functions to enable and disable the instruction cache on MicroBlaze.

void microblaze_enable_icache(void)

This functions enables the instruction cache on MicroBlaze. When MicroBlaze starts up, the instruction cache is disabled. The ICache must be explicitly turned on using this function.

Page 26: Edk Libs Ref Guide

26 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 4: Standalone Board Support PackageR

void microblaze_disable_icache(void)

This function disables the instruction cache on MicroBlaze.

void microblaze_update_icache (int tag, int instr, int lock_valid)

This function updates the cache tag with the appropriate instr. The function disables the cache before updating the tag line. The MSR is restored back to its original value after the cache is updated.

This function can also be used to invalidate and lock the cache depending on the value of the lock_valid parameter. The effect of this parameter is summarized in Table 4-1.

void microblaze_init_icache_range (int cache_addr, int cache_size)

The icache can be initialized using the function microblaze_init_icache_range. This function can be used for initializing the entire icache or only a part of it. The parameter cache_addr indicate the beginning of the cache location, which is to be initialized. The cache_size represents the size from cache_addr, which needs to be initialized.

For example, microblaze_init_icache_range (0x00000300, 0x100) will initialize the instruction cache region between 0x300 to 0x3ff (0x100 bytes of cache memory is cleared starting from 0x300).

Data Cache HandlingThe microblaze_enable_dcache.s and microblaze_disable_dcache.s files contain functions to enable and disable the data cache on MicroBlaze.

void microblaze_enable_dcache(void)

This functions enables the data cache on MicroBlaze. When MicroBlaze starts up, the data cache is disabled. The Dcache must be explicitly turned on using this function.

void microblaze_disable_dcache(void)

This function disables the instruction cache on MicroBlaze.

Table 4-1: Effect of lock_valid parameter

Lock Valid lock_valid Effect

0 0 0 Invalidate Cache

0 1 1 Valid, but unlocked cacheline. The same cacheline can be used for more than one addresses, if required.The previous address will be swapped out of the cache and written to the memory

1 0 2 Invalidate Cache, No effect of lock bit

1 1 3 Valid cache and locked cacheline. The cacheline is now locked to a particular address. Other addresses cannot use this cacheline.

Page 27: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 27UG114 (v3.0) June 22, 2004 1-800-255-7778

MicroBlaze BSPR

void microblaze_update_dcache (int tag, int data, int lock_valid)

This function updates the cache tag with the appropriate data. The function disables the cache before updating the tag line. The MSR is restored back to its original value after the cache is updated.

This function can also be used to invalidate and lock the cache, depending on the value of the lock_valid parameter. The effect of this parameter is summarized in Table 4-1.

void microblaze_init_dcache_range (int cache_addr, int cache_size)

The icache can be initialized using the function microblaze_init_dcache_range. This function can be used for initializing the entire icache or only a part of it. The parameter cache_addr indicate the beginning of the cache location, which is to be initialized. The cache_size represents the size from cache_addr, which needs to be initialized.

For example, microblaze_init_dcache_range (0x00000300, 0x100) will initialize the data cache region between 0x300 to 0x3ff (0x100 bytes of cache memory is cleared starting from 0x300).

Fast Simplex Link Interface MacrosThe Fast Simplex Link (FSL) interfaces on MicroBlaze can be used in several ways.

microblaze_bread_datafsl(val, id)

This macro performs a blocking data get function on an input FSL of MicroBlaze. id is the FSL identifier and can range from 0 to 7.

microblaze_bwrite_datafsl(val, id)

This macro performs a blocking data put function on an output FSL of MicroBlaze. id is the FSL identifier and can range from 0 to 7.

microblaze_nbread_datafsl(val, id)

This macro performs a non-blocking data get function on an input FSL of MicroBlaze. id is the FSL identifier and can range from 0 to 7.

microblaze_nbwrite_datafsl(val, id)

This macro performs a non- blocking data put function on an output FSL of MicroBlaze. id is the FSL identifier and can range from 0 to 7.

microblaze_bread_cntlfsl(val, id)

This macro performs a blocking control get function on an input FSL of MicroBlaze. id is the FSL identifier and can range from 0 to 7.

microblaze_bwrite_cntlfsl(val, id)

This macro performs a blocking control put function on an output FSL of MicroBlaze. id is the FSL identifier and can range from 0 to 7.

Page 28: Edk Libs Ref Guide

28 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 4: Standalone Board Support PackageR

microblaze_nbread_cntlfsl(val, id)

This macro performs a non-blocking control get function on an input FSL of MicroBlaze. id is the FSL identifier and can range from 0 to 7.

microblaze_nbwrite_cntlfsl(val, id)

This macro performs a non-blocking data control function on an output FSL of MicroBlaze. id is the FSL identifier and can range from 0 to 7.

PowerPC BSPWhen the user system contains a PowerPC, and no Operating System, the Library Generator automatically builds the Stand-Alone BSP in the project library libxil.a.

The Stand-Alone BSP contains boot code, cache, file and memory management, configuration, exception handling, time and processor specific include functions.

Boot CodeThe boot.S, crt0.S, and eabi.S files contain a minimal set of code for initializing the processor and starting an application.

boot.S

Code in the boot.S consists of the two sections boot and boot0. The boot section contains only one instruction that is labeled with _boot. During the link process, this instruction is mapped to the reset vector and the _boot label marks the application’s entry point. The boot instruction is a jump to the _boot0 label. The _boot0 label must reside within a ±23-bit address space of the _boot label. It is defined in the boot0 section. The code in the boot0 section calculates the 32-bit address of the _start label and jumps to it.

crt0.S

Code in the crt0.S file starts executing at the _start label. It initializes the .sbss and .bss sections to zero, as required by the ANSI C specification, sets up the stack, initializes some processor registers, and calls the main() function.

The program remains in an endless loop on return from main().

eabi.S

When an application is compiled and linked with the -msdata=eabi option, GCC inserts a call to the __eabi label at the beginning of the main() function. This is the place where register R13 must be set to point to the .sdata and .sbss data sections and register R2 must be set to point to the .sdata2 read-only data section.

Code in eabi.S sets these two registers to the correct values. The _SDA_BASE_ and _SDA2_BASE_ labels are generated by the linker.

CacheThe xcache_l.c file and corresponding xcache_l.h include file provide access to cache and cache-related operations.

Page 29: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 29UG114 (v3.0) June 22, 2004 1-800-255-7778

PowerPC BSPR

void XCache_WriteCCR0(unsigned int val);

The XCache_WriteCCR0() function writes an integer value to the CCR0 register. Below is a sample code sequence. Before writing to this register, the instruction cache must be enabled to prevent a lockup of the processor core. After writing the CCR0, the instruction cache can be disabled, if not needed.

...XCache_EnableICache(0x80000000) /* enable instruction cache for first 128 MB memory region */XCache_WriteCCR0(0x2700E00) /* enable 8 word pre-fetching */XCache_DisableICache() /* disable instruction cache */...

void XCache_EnableDCache(unsigned int regions);

The XCache_EnableDCache() function enables the data cache for a specific memory region. Each bit in the regions parameter represents 128 MB of memory.

A value of 0x80000000 enables the data cache for the first 128 MB of memory (0 - 0x7FFFFFF). A value of 0x1 enables the data cache for the last 128 MB of memory (0xF8000000 - 0xFFFFFFFF).

void XCache_DisableDCache(void);

The XCache_DisableDCache() function disables the data cache for all memory regions.

void XCache_FlushDCacheLine(unsigned int adr);

The XCache_FlushDCacheLine() function flushes and invalidates the data cache line that contains the address specified by the adr parameter. A subsequent data access to this address results in a cache miss and a cache line refill.

void XCache_StoreDCacheLine(unsigned int adr);

The XCache_StoreDCacheLine() function stores in memory the data cache line that contains the address specified by the adr parameter. A subsequent data access to this address results in a cache hit if the address was already cached; otherwise, it results in a cache miss and cache line refill.

void XCache_EnableICache(unsigned int regions);

The XCache_EnableICache() function enables the instruction cache for a specific memory region. Each bit in the regions parameter represents 128 MB of memory.

A value of 0x80000000 enables the instruction cache for the first 128 MB of memory (0 - 0x7FFFFFF). A value of 0x1 enables the instruction cache for the last 128 MB of memory (0xF8000000 - 0xFFFFFFFF).

void XCache_DisableICache(void);

The XCache_DisableICache() function disables the instruction cache for all memory regions.

Page 30: Edk Libs Ref Guide

30 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 4: Standalone Board Support PackageR

void XCache_InvalidateICache(void);

The XCache_InvalidateICache() function invalidates the whole instruction cache. Subsequent instructions produce cache misses and cache line refills.

void XCache_InvalidateICacheLine(unsigned int adr);

The XCache_InvalidateICacheLine() function invalidates the instruction cache line that contains the address specified by the adr parameter. A subsequent instruction to this address produces a cache miss and a cache line refill.

Exception HandlingThis section documents the exception handling API that is provided in the Board Support Package. For an in-depth explanation on how exceptions and interrupts work on the PPC405, please refer to the chapter “Exceptions and Interrupts” in the PPC User’s Manual.

The exception handling API consists of a set of the files xvectors.S, xexception_l.c, and the corresponding header file xexception_l.h.

void XExc_Init(void);

This function sets up the interrupt vector table and registers a “do nothing” function for each exception. This function has no parameters and does not return a value.

This function must be called before registering any exception handlers or enabling any interrupts. When using the exception handler API, this function should be called at the beginning of your main() routine.

IMPORTANT: If you are not using the default linker script, you need to reserve memory space for storing the vector table in your linker script. The memory space must begin on a 64k boundary. The linker script entry should look like this example:

.vectors : { . = ALIGN(64k); *(.vectors) }

For further information on linker scripts, please refer to the Linker documentation.

Page 31: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 31UG114 (v3.0) June 22, 2004 1-800-255-7778

PowerPC BSPR

void XExc_RegisterHandler(Xuint8 ExceptionId, XExceptionHandler Handler, void *DataPtr);

This function is used to register an exception handler for a specific exception. It does not return a value. Please refer to Table 4-2 for a list of parameters.

The function provided as the Handler parameter must have the following function prototype:

Table 4-2: Exception Handler Parameters

Parameter Name Parameter Type Description

ExceptionId Xuint8 Exception to which this handler should be registered. The type and the values are defined in the header file xexception_l.h. Please refer to Table 4-3 for possible values.

Handler XExceptionHandler Pointer to the exception handling function

DataPtr void * User value to be passed when the handling function is called

Table 4-3: Registered Exception Types and Values

Exception Type Value

XEXC_ID_JUMP_TO_ZERO 0

XEXC_ID_MACHINE_CHECK 1

XEXC_ID_CRITICAL_INT 2

XEXC_ID_DATA_STORAGE_INT 3

XEXC_ID_INSTUCTION_STORAGE_INT 4

XEXC_ID_NON_CRITICAL_INT 5

XEXC_ID_ALIGNMENT_INT 6

XEXC_ID_PROGRAM_INT 7

XEXC_ID_FPU_UNAVAILABLE_INT 8

XEXC_ID_SYSTEM_CALL 9

XEXC_ID_APU_AVAILABLE 10

XEXC_ID_PIT_INT 11

XEXC_ID_FIT_INT 12

XEXC_ID_WATCHDOG_TIMER_INT 13

XEXC_ID_DATA_TLB_MISS_INT 14

XEXC_ID_INSTRUCTION_TLB_MISS_INT 15

XEXC_ID_DEBUG_INT 16

Page 32: Edk Libs Ref Guide

32 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 4: Standalone Board Support PackageR

typedef void (*XExceptionHandler)(void * DataPtr);

This prototype is declared in the xexception_l.h header file.

When this exception handler function is called, the parameter DataPtr will contain the same value as you provided when you registered the handler.

void XExc_RemoveHandler(Xuint8 ExceptionId)

This function is used to deregister a handler function for a given exception. For possible values of parameter ExceptionId, please refer to Table 4-3.

void XExc_mEnableExceptions (EnableMask);

This macro is used to enable exceptions. It must be called after initializing the vector table with function exception_Init and registering exception handlers with function XExc_RegisterHandler. The parameter EnableMask is a bitmask for exceptions to be enabled. The EnableMask parameter may have the values XEXC_CRITICAL, XEXC_NON_CRITICAL or XEXC_ALL.

void XExc_mDisableExceptions (DisableMask);

This macro is called to disable exceptions. The parameter DisableMask is a bitmask for exceptions to be disabled.The DisableMask parameter may have the values XEXC_CRITICAL, XEXC_NON_CRITICAL or XEXC_ALL.

FilesFile support is limited to the stdin and stdout streams. In such an environment, the following functions do not make much sense:

� open() (in open.c)

� close() (in close.c)

� fstat() (in fstat.c)

� unlink() (in unlink.c)

� lseek() (in lseek.c)

These files are included for completeness and because they are referenced by the C library.

int read(int fd, char *buf, int nbytes);

The read() function in read.c reads nbytes bytes from the standard input by calling inbyte(). It blocks until all characters are available, or the end of line character is read. Read() returns the number of characters read. The parameter fd is ignored.

int write(int fd, char *buf, int nbytes);

The write() function in write.c writes nbytes bytes to the standard output by calling outbyte(). It blocks until all characters have been written. Write() returns the number of characters written. The parameter fd is ignored.

int isatty(int fd);

The isatty() function in isatty.c reports if a file is connected to a tty. This function always returns 1, since only the stdin and stdout streams are supported.

Page 33: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 33UG114 (v3.0) June 22, 2004 1-800-255-7778

PowerPC BSPR

Memory Management

char *sbrk(int nbytes);

The sbrk() function in the sbrk.c file allocates nbytes of heap and returns a pointer to that piece of memory. This function is called from the memory allocation functions of the C library.

ProcessThe functions getpid() in getpid.c and kill() in kill.c are included for completeness and because they are referenced by the C library.

Processor-Specific Include Files The xreg405.h include file contains the register numbers and the register bits for the PPC 405 processor.

The xpseudo-asm.h include file contains the definitions for the most often used inline assembler instructions.

These inline assembler instructions can be used from drivers and user applications written in C.

TimeThe xtime_l.c file and corresponding xtime_l.h include file provide access to the 64-bit time base counter inside the PowerPC core. The counter increases by one at every processor cycle.

The sleep.c file and corresponding sleep.h include file implement functions for tired programs. All sleep functions are implemented as busy loops.

typedef unsigned long long XTime;

The XTime type in xtime_l.h represents the Time Base register. This struct consists of the Time Base Low (TBL) and Time Base High (TBH) registers, each of which is a 32-bit wide register. The definition of XTime is as follows:

typedef unsigned long long XTime;

void XTime_SetTime(XTime xtime);

The XTime_SetTime() function in xtime_l.c sets the time base register to the value in xtime.

void XTime_GetTime(XTime *xtime);

The XTime_GetTime() function in xtime_l.c writes the current value of the time base register to variable xtime.

void XTime_TSRClearStatusBits(unsigned long Bitmask);

The XTime_TSRClearStatusBits() function in xtime_l.c is used to clear bits in the Timer Status Register (TSR). The parameter Bitmask designates the bits to be cleared. A one in any

Page 34: Edk Libs Ref Guide

34 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 4: Standalone Board Support PackageR

position of the Bitmask parameter clears the corresponding bit in the TSR. This function does not return a value.

The header file xreg405.h defines the following values for the Bitmask parameter:

Example:

XTime_TSRClearStatusBits(TSR_CLEAR_ALL);

void XTime_PITSetInterval(unsigned long interval);

The XTime_PITSetInterval() function in xtime_l.c is used to load a new value into the Programmable-Interval Timer Register. This register is a 32-bit decrementing counter clocked at the same frequency as the time-base register. Depending on the AutoReload setting the PIT is automatically reloaded with the last written value or has to be reloaded manually. This function does not return a value.

Example:

XTime_PITSetInterval(0x00ffffff);

void XTime_PITEnableInterrupt(void);

The XTime_PITEnableInterrupt() function in xtime_l.c enables the generation of PIT interrupts. An interrupt occurs when the PIT register contains a value of 1, and is then decremented. This function does not return a value. XExc_Init() must be called, the PIT interrupt handler must be registered, and exceptions must be enabled before calling this function.

Table 4-4: Bitmask Parameter Values

Name Value Description

XREG_TSR_WDT_ENABLE_NEXT_WATCHDOG 0x80000000 Clearing this bit disables the watchdog timer event.

XREG_TSR_WDT_INTERRUPT_STATUS 0x40000000 Clears the Watchdog Timer Interrupt Status bit. This bit is set after a watchdog interrupt occurred, or could have occurred had it been enabled.

XREG_TSR_WDT_RESET_STATUS_11 0x30000000 Clears the Watchdog Timer Reset Status bits. These bits Specify the kind of reset that occurred as a result of a watchdog timer event.

XREG_TSR_PIT_INTERRUPT_STATUS 0x08000000 Clears the Programmable Interval Timer Status bit. This bit is set after a PIT interrupt has occurred.

XREG_TSR_FIT_INTERRUPT_STATUS 0x04000000 Clears the Fixed Interval Timer Status bit. This bit is set after a FIT interrupt has occurred.

XREG_TSR_CLEAR_ALL 0xFFFFFFFF Clears all bits in the TSR. After a Reset, the content of the TSR is not specified. Use this Bitmask to clear all bits in the TSR.

Page 35: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 35UG114 (v3.0) June 22, 2004 1-800-255-7778

PowerPC BSPR

Example:

XTime_PITEnableInterrupt();

void XTime_PITDisableInterrupt(void);

The XTime_PITDisableInterrupt() function in xtime_l.c disables the generation of PIT interrupts. It does not return a value.

Example:

XTime_PITDisableInterrupt();

void XTime_PITEnableAutoReload(void);

The XTime_PITEnableAutoReload() function in xtime_l.c enables the auto-reload function of the PIT Register. When auto-reload is enabled the PIT Register is automatically reloaded with the last value loaded by calling the XTime_PITSetInterval function when the PIT Register contains a value of 1 and is decremented. When auto-reload is enabled, the PIT Register never contains a value of 0. This function does not return a value.

Example:

XTime_PITEnableAutoReload();

void XTime_PITDisableAutoReload(void);

The XTime_PITDisableAutoReload() function in xtime_l.c disables the auto-reload feature of the PIT Register. When auto-reload is disabled the PIT decrements from 1 to 0. If it contains a value of 0 it stops decrementing until it is loaded with a non-zero value. This function does not return a value.

Example:

XTime_PITDisableAutoReload();

void XTime_PITClearInterrupt(void);

The XTime_PITClearInterrupt() function in xtime_l.c is used to clear PIT-Interrupt-Status bit in the Timer-Status Register. This bit specifies whether a PIT interrupt occurred. You must call this function in your interrupt-handler to clear the Status bit, otherwise another PIT interrupt will occur immediately after exiting the interrupt –handler function. This function does not return a value. Calling this function is equivalent to calling XTime_TSRClearStatusBits(XREG_TSR_PIT_INTERRUPT_STATUS).

Example:

XTime_PITClearInterrupt();

unsigned int usleep(unsigned int __useconds);

The usleep() function in sleep.c delays the execution of a program by __useconds microseconds. It always returns zero. This function requires that the processor frequency (in Hz) is defined. The default value of this variable is 400MHz. This value can be overwritten in the MSS file as follows:

BEGIN PROCESSOR

Page 36: Edk Libs Ref Guide

36 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 4: Standalone Board Support PackageR

PARAMETER HW_INSTANCE = PPC405_iPARAMETER DRIVER_NAME = cpu_ppc405PARAMETER DRIVER_VER = 1.00.aPARAMETER CORE_CLOCK_FREQ_HZ = 20000000END

The file xparameters.h can also be modified with the correct value, as follows:

#define XPAR_CPU_PPC405_CORE_CLOCK_FREQ_HZ 20000000

unsigned int sleep(unsigned int __seconds);

The sleep() function in sleep.c delays the execution of a program by __seconds seconds. It always returns zero.This function requires that the processor frequency (in Hz) is defined. The default value of this variable is 400MHz. This value can be overwritten in the MSS file as follows:

BEGIN PROCESSORPARAMETER HW_INSTANCE = PPC405_iPARAMETER DRIVER_NAME = cpu_ppc405PARAMETER DRIVER_VER = 1.00.aPARAMETER CORE_CLOCK_FREQ_HZ = 20000000END

The file xparameters.h can also be modified with the correct value, as follows:

#define XPAR_CPU_PPC405_CORE_CLOCK_FREQ_HZ 20000000

int nanosleep(const struct timespec *rqtp, struct timespec *rmtp);

The nanosleep() function in sleep.c is currently not implemented. It is a placeholder for linking applications against the C library. It always returns zero.

Page 37: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 37UG114 (v3.0) June 22, 2004 1-800-255-7778

R

Chapter 5

Xilkernel

This chapter describes Xilkernel, a kernel for the Xilinx embedded processors. The chapter contains the following sections.

� “Overview”

� “Key Features”

� “Xilkernel Blocks”

� “Xilkernel Modes”

� “Building Xilkernel Applications”

� “Xilkernel Process Model”

� “Xilkernel Scheduling Model”

� “Xilkernel API”

� “Interrupt Handling”

� “Kernel Customization”

� “Debugging Xilkernel”

� “Memory Footprint”

� “Xilkernel File Organization”

� “System Initialization”

� “Limitations”

� “Future Enhancements”

� “Modifying Xilkernel”

� “User Guide”

OverviewXilkernel is a small, robust and modular kernel that allows a very high degree of customization, letting users tailor the kernel to an optimal level both in terms of size and functionality. It supports the core features required in an embedded/real-time kernel, with a POSIX API. Xilkernel works on both the MicroBlaze and PowerPC processors. Xilkernel IPC services can be used to implement higher level services like networking, video, audio and subsequently, run applications using these services.

Key FeaturesXilkernel has the following notable features:

� An API closely supporting a subset of POSIX that targets embedded kernels.

Page 38: Edk Libs Ref Guide

38 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 5: XilkernelR

� Kernel implementation of core functionality, such as

� Process Management

� Thread Management

� Synchronization services - Semaphores and Mutex Locks

� IPC services - Message Queues and Shared Memory

� Dynamic Block Memory Allocation

� User level interrupt handling API

� Highly scalable kernel that can be accommodated into a given system through the inclusion or exclusion of functionality as required.

� Easy kernel configuration with XPS, MLD, and MSS mechanisms.

� Support for static task undesired specification.

� Configurable scheduling - priority-driven preemptive scheduling or round-robin scheduling.

� System call interface to the kernel.

Xilkernel BlocksThe kernel is highly modular in design. The user can select and customize the kernel modules that are needed for the application at hand. Customizing the kernel is discussed in detail in the “Kernel Customization” section(1). Figure 5-1 shows the various modules of Xilkernel.

1. Some of these features might not be fully supported in a given release of xilkernel

Figure 5-1: Xilernel Modules

System Call Handler Interrupt HandlerScheduler

ThreadManagement

MessageQueue

ProcessManagement

SharedMemory

Semaphores

User ApplicationEg. Webserver User Interrupts

System CallLibrary

Timer Interrupt forContext Switch

Dynamic BufferManagement

Xilkernel

Xilkernel Modules

X10131

Page 39: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 39UG114 (v3.0) June 22, 2004 1-800-255-7778

Xilkernel ModesR

Xilkernel ModesXilkernel and user applications can be built in two different modes:

� Separate Executable mode

In this mode, the user applications and kernel can be built as separate executables.Application entry points can be specified as addresses in the MSS process/pthreadsconfiguration, using the parameters separate_exec_process_table andseparate_exec_pthread_table in libgen configuration. Applications can get servicesfrom the kernel using the system call interface. These system call wrappers can beobtained by linking the application with libsyscall.a.This mode provides the flexibilityof developing and dynamically loading each application separately. The stack for theuser application will have to be separately setup as a part of each elf file and the kerneldoes no special stack setup. xilkernel.elf is generated only if the process contexts are notconfigured in the next mode in the OS specification.

� Kernel Bundled Executable mode

In this mode, the user applications and kernel are bundled and built together as asingle executable elf file. The entry point for an application is a function name that isspecified using parameters kernel_bundled_process_table andkernel_bundled_pthread_table in the MSS. Building xilkernel using libgen generateslibxilkernel.a library. This can be linked with all the user applications which need to runon xilkernel, to generate a single kernel bundled executable. Since all the userapplications are part of a single executable, symbol names, such as global variablesand function names, should be unique. Though user applications can directly call thesys_ prefixed system calls, they would have to lock and unlock the kernel beforecalling the system calls. To simplify this process, applications in single executablemode have access to a thin library layer of system call wrappers that lock the kernel,execute the system call and then unlock the kernel. Stack is setup by the kernel onbehalf of the single elf applications.The kernel bundled executable mode is a superset ofthe separate executable mode. Applications that are separate executables can stillinterface with the single executable kernel image dynamically, using the system callAPI in libsyscall.a. These system calls will be handled by the system call handlers thatare present in the kernel image.Building and linking applications in the two xilkernelmodes is illustrated in Figure 5-2.

Building Xilkernel Applications� Applications should define __XMK__ when being compiled. Defining this flag makes

available certain definitions and declarations from the GNU include files that are required by Xilkernel and applications. Therefore, -D__XMK__ should accompany the compiler flags of any user applications.

� In the separate executable mode, microblaze applications should use the linker flag -xl-mode-xilkernel to prevent their crt code from overwriting the interrupt and exception vectors, setup by Xilkernel, in memory. In PowerPC, a different linker script other than the default linker script, must be used to prevent the crt from overwriting Xilkernel sections. This linker script should basically look to not include the boot section in the elf image.

� In the kernel bundle mode, Microblaze applications should use one of the two linker flags, -xl-mode-executable or -xl-mode-xmdstub, to link the final application image. The two choices depend on if XMDSTUB is used for debugging or not. In PowerPC, kernel bundle applications must use the same top-level linker script that is present in the Xilkernel source folder, within the main processor folder. For e.g if the processor

Page 40: Edk Libs Ref Guide

40 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 5: XilkernelR

instance is called ppc405_0, then the application must use ppc405_0/libsrc/xilkernel_v2_00_a/src/linker_script.sh when forming the final kernel bundle image. This is because, this linker script configures the vectors, code and data sections, either according to the linker script configuration in the MSS, or using default values.

Refer to the Xilkernel user guide and the accompanying design examples for specific illustrations of the above concepts.

The system call interface for both these xilkernel modes are illustrated in Figure 5-3. Applications that are a part of the kernel image have the advantage of relatively smaller system call latency as compared to those in separate executable mode, which requires another layer of indirection in the system call handler level.

Figure 5-2: Building Applications for Xilkernel

Kernel Sources

libsyscall.a

Separate Executable Mode

xilkernel.elf

libsyscall.a

libsyscall.a

+

+

Executable

Executable

User Sources

libxilkernel.a

Kernel Bundled Executable Mode

libxilkernel.a

X10129

Kernel BundledApplicationKernel and Application

.elf files

+

User Sources

Page 41: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 41UG114 (v3.0) June 22, 2004 1-800-255-7778

Xilkernel Process ModelR

Debugging applications in the two modes is different. See the “Debugging Xilkernel” section for more details about debugging the applications and the kernel.

Xilkernel Process ModelXilkernel supports the concepts of, both, processes and threads. Processes as well as threads are multiplexed on top of process contexts in the kernel. Scheduling is done at the process context level. Therefore threads and processes contend among each other for getting scheduled on the processor. The only distinction between threads and processes in Xilkernel is that, except for pthread_create, all other pthread_ calls, are valid only from within threads. This includes the basic pthread interfaces and the pthread_mutex interfaces that are supported by Xilkernel. All the other interfaces work exactly the same irrespective of whether they are invoked from threads or processes. Both threads and processes could be statically created from separate elf files or from locations within a single elf file. Threads are not light-weight in any respect, as compared to processes. There is no protection between memory segments and therefore both processes and threads can share each other’s memory. The only other difference processes and threads is that processes that are created dynamically are assumed to be elf files that have a stack allocated as a part of the elf file image. Depending on the programming model that the user employs, either processes or threads or a mixture of both might be chosen for the system design. From henceforth in this document, the term processes would encompass both threads and processes, while threads would refer to pthreads alone.

Note:1. The total number of process context structures that are allocated statically in the kernel depends on the sum of the configured maximum number of processes and threads. i.e. maximum number of process contexts allowed in the system.2. Xilkernel does not feature a loader when creating new processes and threads. It creates process and thread contexts to start of from memory images assumed to be initialized. Therefore, if any elf file depends on initialized data sections, then the next time the same memory image is used to create a

Figure 5-3: Xilkernel System Call Interface

Proc3Proc2Proc1

User Space

System Call Handler

Pure Separate Executable Mode Scenario

xilkernel.elf

Kernel Image

Proc6Proc5Proc4

User Space

System Call Handler

Kernel Bundled Executable Mode Scenario

libxilkernel.a

Sys

tem

Cal

lW

rapp

ers

Kernel Image

X10128

Proc1

Proc2

Proc3

Page 42: Edk Libs Ref Guide

42 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 5: XilkernelR

process, the initialized sections will be invalid, unless some external mechanism is used to reload the elf image before creating the process.

Xilkernel Scheduling ModelXilkernel supports either priority-driven preemptive scheduling (SCHED_PRIO) or round-robin (SCHED_RR) scheduling. This must be configured statically at kernel generation time. In SCHED_RR, there is a single ready queue and each process context executes for a configured time slice before yielding execution to the next process context in the queue. In SCHED_PRIO there are as many ready queues as there are priority levels. Priority 0 is the highest priority in the system and higher values mean lower priority. As shown in Figure 5-4, the process that is at the head of the highest priority ready queue always scheduled to execute next. Within the same priority level, scheduling is round robin. Empty ready queue levels are skipped and the next ready queue level is examined for schedulable processes. Blocked processes are off their ready queues and in their appropriate wait queues. The number of priority levels can be configured for SCHED_PRIO. For both the scheduling models, the length of the ready queue can also be configured. If there are wait queues inside the kernel (in semaphores, message queues etc.), they are configured as priority queues if scheduling mode is SCHED_PRIO.

Each process context is in any of the following five states:

� PROC_NEW

� PROC_READY

� PROC_RUN

� PROC_WAIT

� PROC_DEAD

The process context state diagram is shown in Figure 5-5.

Figure 5-4: Priority Driven Scheduling

A0

1

2

13

14

15

B

Active

C D(Blocked)

E

Prio

rity

F

G(Blocked)

X10132

Page 43: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 43UG114 (v3.0) June 22, 2004 1-800-255-7778

Xilkernel APIR

Xilkernel API

Process ManagementA process is created and handled using the following interfaces.Some of the functions are optional and can be configured in during system initialization. Refer to the “Customizing Process Management” section for more details. Currently, a specific process_exit call is required at the end of the process’s code to allow the operating system to reclaim the process’s resources.

Figure 5-5: Process Context States

Activated

PROC_READY PROC_WAIT

PROC_NEW PROC_RUN PROC_DEAD

X10130

Term

inate

d

Unblocked

Term

inat

ed

Terminated

Sche

dule

d in

Sche

dule

d ou

t

Blocked

Unblocked

int process_create (unsigned int start_addr, int priority)

Parameters start_addr is the start address of the process

priority is the starting priority of the process in the system.

Returns Returns the PID of the new process on success.

Returns -1 on failure.

Description Creates a new process. Allocates a new PID and Process Control Block (PCB) for the process.The process is placed in the appropriate ready queue. Calls the scheduler if scheduling is priority driven.

Includes sys/process.h

Page 44: Edk Libs Ref Guide

44 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 5: XilkernelR

int process_exit (void)

Parameters None

Returns None

Description Removes the process from the system. Schedules the next process in the system.

Caution! Do not use this to terminate a thread (described later on).

Includes sys/process.h

int process_kill (char pid)

Parameters pid is the PID of process to kill

Returns Returns 0 on success.

Returns -1 on failure.

Description Removes the process with pid from the system. No indication is given to other processes that depend on this process.

Note This function is optionally configured using CONFIG_PROCESS_KILL

Includes sys/process.h

int process_status (int pid, p_stat *ps)

Parameters pid is the PID of process

ps is the buffer where the process status is returned

Returns Returns process status in ps on success

Returns NULL in ps on failure.

Description Get the status of the process or thread, whose pid is pid. The status is returned in structure p_stat which has the following fields:

� pid is the process ID

� state is the current state of the process

The contents of p_stat are defined in the <sys/ktypes.h> header.

Includes sys/process.h

int process_yield (void)

Parameters None

Returns None

Description Yields the processor to the next process or thread.The current process goes to PROC_READY state and is put at the end of the ready queue.

Note This function is optionally configured using CONFIG_PROCESS_YIELD.

Includes sys/process.h

Page 45: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 45UG114 (v3.0) June 22, 2004 1-800-255-7778

Xilkernel APIR

Thread ManagementXilkernel supports the basic POSIX threads API. A thread is scheduled and allocated in the same way as a process. Threads created in the system have a kernel wrapper to which they return control to when they terminate. Therefore a specific exit function is not required at the end of the thread’s code. Thread stack is allocated on the thread’s behalf from a pool of bss memory that is statically allocated depending on the maximum number of threads in the system. Therefore, threads created dynamically are not required to be associated with an elf file. The entire thread module is optional and can be configured in or out as a part of the software specification. See the “Customizing Thread Management” section for more

int process_setpriority (int priority)

Parameters priority is the new priority of the process.

Returns On success, return 0

On failure, return -1

Description Sets the priority of current process or thread to new value.

Includes sys/process.h

int process_getpriority (void)

Parameters None

Returns Priority of the current process.

Description Gets the priority of the current process or thread.

Includes sys/process.h

int get_currentPID (void)

Parameters None

Returns Process ID of current process or thread.

Description Gets the Process ID of process context that is executing currently.

Includes sys/process.h

Page 46: Edk Libs Ref Guide

46 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 5: XilkernelR

details on customizing this module. The thread management interface is summarized below.

int pthread_create (pthread_t thread, pthread_attr_t* attr, void* (*start_func)(void*), void* param)

Parameters thread is the location to store the created thread’s identifier.

attr is the pointer to thread creation attributes structure.

start_func is the start address of the function from which the thread needs to execute

param is the pointer argument to the thread function

Returns Returns 0 and thread id of the created thread in *thread, on success.

Returns -1 if thread refers to an invalid location.

Returns EINVAL if attr refers to invalid attributes.

Returns EAGAIN if resources unavailable to create the thread.

Description The pthread_create() function creates a new thread, with attributes specified by attr, within a process. If attr is NULL, the default attributes are used. If the attributes specified by attr are modified later, the thread’s attributes are not be affected. Upon successful completion, pthread_create() stores the ID of the created thread in the location referenced by thread.

The thread is created executing start_routine with arg as its sole argument. If the start_routine returns, the effect is as if there was an implicit call to pthread_exit() using the return value of start_routine as the exit status. This exit behavior is slightly different for the main thread. This is explained in the pthread_exit description.

Includes pthread.h

void pthread_exit (void *value_ptr)

Parameters value_ptr is a pointer to the return value of the thread.

Returns None

Description The pthread_exit() function will terminate the calling thread and make the value value_ptr available to any successful join with the terminating thread. Thread termination releases process context resources, including, but not limited to, memory and attributes. An implicit call to pthread_exit() is made when a returns from the start routine that was used to create it. The function’s return value serves as the thread’s exit status.

Caution! There is no implicit thread exit invoked at the end of a thread created out of an elf file by specifying the start address of the executable instructions in the elf file. Control returns to an exit stub which loops indefinitely. Therefore, to terminate such threads an explicit call to this thread exit routine is required.

Includes pthread.h

Page 47: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 47UG114 (v3.0) June 22, 2004 1-800-255-7778

Xilkernel APIR

int pthread_join (pthread_t thread, void **value_ptr)

Parameters value_ptr is a pointer to the return value of the thread.

Returns 0 on success

Returns ESRCH if the target thread is not in a joinable state or is an invalid thread.

Returns EINVAL if the target thread already has someone waiting to join with it.

Description The pthread_join() function suspends execution of the calling thread until the target thread terminates, unless the target thread has already terminated. On return from a successful pthread_join() call with a non-NULL value_ptr argument, the value passed to pthread_exit() by the terminating thread is made available in the location referenced by value_ptr. When a pthread_join() returns successfully, the target thread has been terminated. The results of multiple simultaneous calls to pthread_join() specifying the same target thread are that only one thread succeeds and the others fail with EINVAL.

Note: No deadlock detection is provided.

Includes pthread.h

pthread_t pthread_self (void)

Parameters None

Returns On success, returns thread identifier of current thread.

Error behavior not defined.

Description The pthread_self() function returns the thread ID of the calling thread.

Includes pthread.h

int pthread_detach (pthread_t target)

Parameters target is the target thread to detach.

Returns Returns 0 on success.

Returns ESRCH if target thread cannot be found.

Description The pthread_detach() function indicates to the implementation that storage for the thread thread can be reclaimed when that thread terminates. If thread has not terminated, pthread_detach() will not cause it to terminate. The effect of multiple pthread_detach() calls on the same target thread is unspecified.

Includes pthread.h

Page 48: Edk Libs Ref Guide

48 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 5: XilkernelR

int pthread_equal (pthread_t t1, pthread_t t2)

Parameters t1 and t2 are the two thread identifiers to compare.

Returns Returns 1 if t1 and t2 refer to threads that are equal.

Returns 0 otherwise.

Description The pthread_equal() function returns a non-zero value if t1 and t2 are equal; otherwise, zero is returned.If either t1 or t2 are not valid thread IDs, zero is returned.

Includes pthread.h

int pthread_attr_init (pthread_attr_t* attr)

Parameters attr is a pointer to the attribute structure to be initialized.

Returns Returns 0 on success, 1 on failure.

Returns EINVAL on invalid attr parameter.

Description The pthread_attr_init() function initializes a thread attributes object attr with the default value for all of the individual attributes used by a given implementation. The contents of pthread_attr_t are defined in the <sys/types.h> header.

Note: This does not make a call into the kernel.

Includes pthread.h

int pthread_attr_destroy (pthread_attr_t* attr)

Parameters attr is a pointer to the thread attributes that have to be destroyed.

Returns Returns 0 on success.

Returns EINVAL on errors.

Description The pthread_attr_destroy() function destroys a thread attributes object. The implementation causes pthread_attr_destroy() to set attr to an implementation-defined invalid value. A destroyed attr attributes object can be re-initialized using pthread_attr_init(); the results of otherwise referencing the object after it has been destroyed are undefined.

Note: This does not make a call into the kernel.

Includes pthread.h

Page 49: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 49UG114 (v3.0) June 22, 2004 1-800-255-7778

Xilkernel APIR

int pthread_attr_setdetachstate (pthread_attr_t* attr, int dstate)

Parameters attr is the attribute structure on which the operation is to be performed.

dstate is the detachstate required.

Returns Returns 0 on success.

Returns EINVAL on invalid parameters.

Description The detachstate attribute controls whether the thread is created in a detached state. If the thread is created detached, then when the thread exits, the thread’s resources are detached without requiring a pthread_join() or a call pthread_detach().The application can set detachstate to either PTHREAD_CREATE_DETACHED or PTHREAD_CREATE_JOINABLE.

Note: This does not make a call into the kernel.

Includes pthread.h

int pthread_attr_getdetachstate (pthread_attr_t* attr, int *dstate)

Parameters attr is the attribute structure on which the operation is to be performed.

dstate is the location to store the detachstate in.

Returns Returns 0 on success.

Returns EINVAL on invalid parameters.

Description The implementation stores either PTHREAD_CREATE_DETACHED or PTHREAD_CREATE_JOINABLE in dstate, if the value of detachstate was valid in attr.

Note: This does not make a call into the kernel.

Includes pthread.h

int pthread_attr_setschedparam (pthread_attr_t* attr, struct sched_param *schedpar)

Parameters attr is the attribute structure on which the operation is to be performed.

schedpar is the location of the structure that contains the scheduling parameters.

Returns Returns 0 on success.

Returns EINVAL on invalid parameters.

Returns ENOTSUP for invalid scheduling parameters.

Description The pthread_attr_setschedparam() functions sets the scheduling parameter attributes in the attr argument. The contents of the sched_param structure are defined in the <sched.h> header.

Note: This does not make a call into the kernel.

Includes pthread.h

Page 50: Edk Libs Ref Guide

50 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 5: XilkernelR

SemaphoresXilkernel supports kernel allocated POSIX semaphores that can be used for synchronization. POSIX semaphores are counting semaphores that also count below zero (a negative value indicates the number of processes blocked on the semaphore). Xilkernel also supports a few interfaces for working with named semaphores. The number of semaphores allocated in the kernel and the length of semaphore wait queues can be configured during system initialization. Refer to the “Customizing Semaphore” section for more details.The semaphore module is optional and can be configured in or out during system initialization. The message queue module, described later on in this document, uses semaphores. Therefore this module needs to be included if message queues are to be used. The Xilkernel semaphore interface is described below.

int pthread_attr_getschedparam (pthread_attr_t* attr, struct sched_param* schedpar)

Parameters attr is the attribute structure on which the operation is to be performed.

schedpar is the location to store the sched_param structure in.

Returns Returns 0 on success.

Returns EINVAL on invalid parameters.

Description The pthread_attr_getschedparam() gets the scheduling parameter attributes in the attr argument. The contents of the param structure are defined in the <sched.h> header.

Note: This does not make a call into the kernel.

Includes pthread.h

int sem_init (sem_t *sem, int pshared, unsigned value)

Parameters sem is the location to store the created semaphore’s identifier.

pshared indicates sharing status of the semaphore, between processes.

value is the initial count of the semaphore.

Note: pshared is unused currently.

Returns Returns 0 on success.

Returns -1 on failure.

Description The sem_init() function initializes the unnamed semaphore referred to by sem. The value of the initialized semaphore is value. Following a successful call to sem_init(), the semaphore may be used in subsequent calls to sem_wait(), sem_trywait(), sem_post(), and sem_destroy(). This semaphore remains usable until the semaphore is destroyed. Only sem itself may be used for performing synchronization. The result of referring to copies of sem in calls to sem_wait(), sem_trywait(), sem_post(), and sem_destroy() is undefined. Attempting to initialize an already initialized semaphore results in undefined behavior.

Includes semaphore.h

Page 51: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 51UG114 (v3.0) June 22, 2004 1-800-255-7778

Xilkernel APIR

int sem_destroy (sem_t* sem)

Parameters sem is the semaphore to be destroyed.

Returns Returns 0 on success.

Returns -1 on failure.

Description The sem_destroy() function destroys the unnamed semaphore indicated by sem. Only a semaphore that was created using sem_init() may be destroyed using sem_destroy(); the effect of calling sem_destroy() with a named semaphore is undefined. The effect of subsequent use of the semaphore sem is undefined until sem is reinitialized by another call to sem_init().

Includes semaphore.h

int sem_getvalue (sem_t* sem, int* value)

Parameters sem is the semaphore identifier

value is the location where the semaphore value is stored.

Returns Returns 0 on success and value appropriately filled in.

Returns -1 on failure.

Description The sem_getvalue() function updates the location referenced by the sval argument to have the value of the semaphore referenced by sem without affecting the state of the semaphore. The updated value represents an actual semaphore value that occurred at some unspecified time during the call, but it need not be the actual value of the semaphore when it is returned to the calling process.

If sem is locked, then the object to which sval points is set to a negative number whose absolute value represents the number of processes waiting for the semaphore at some unspecified time during the call.

Includes semaphore.h

Page 52: Edk Libs Ref Guide

52 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 5: XilkernelR

int sem_wait (sem_t* sem)

Parameters sem is the semaphore identifier.

Returns Returns 0 on success and the semaphore in a locked state.

Returns -1 on failure.

Description The sem_wait() function locks the semaphore referenced by sem by performing a semaphore lock operation on that semaphore. If the semaphore value is currently zero, then the calling thread does not return from the call to sem_wait() until it either locks the semaphore or the semaphore is forcibly destroyed.

Upon successful return, the state of the semaphore is locked and remains locked until the sem_post() function is executed and returns successfully.

Note: When a process is unblocked within the sem_wait call, where it blocked due to unavailability of the semaphore, the semaphore may have been destroyed forcibly. In such a case, -1 is returned. Semaphores maybe forcibly destroyed due to destroying message queues which internally use semaphores. No deadlock detection is provided.

Includes semaphore.h

int sem_trywait (sem_t* sem)

Parameters sem is the semaphore identifier.

Returns Returns 0 on success.

Returns -1 on failure.

Description The sem_trywait() function locks the semaphore referenced by sem only if the semaphore is currently not locked; that is, if the semaphore value is currently positive. Otherwise, it does not lock the semaphore and returns -1.

Includes semaphore.h

Page 53: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 53UG114 (v3.0) June 22, 2004 1-800-255-7778

Xilkernel APIR

int sem_post (sem_t* sem)

Parameters sem is the semaphore identifier

Returns Returns 0 on success.

Returns -1 on failure.

Description The sem_post() function unlocks the semaphore referenced by sem by performing a semaphore unlock operation on that semaphore.

If the semaphore value resulting from this operation is positive, then no threads were blocked waiting for the semaphore to become unlocked; the semaphore value is simply incremented.

If the value of the semaphore resulting from this operation is zero or negative, then one of the threads blocked waiting for the semaphore is allowed to return successfully from its call to sem_wait(). This is either the first thread on the queue, if scheduling mode is SCHED_RR or, it is the highest priority thread in the queue, if scheduling mode is SCHED_PRIO.

Note: If an unlink operation had been requested on the semaphore, the unlink is performed if the post operation sees that no more processes are waiting on the semaphore.

Includes semaphore.h

Page 54: Edk Libs Ref Guide

54 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 5: XilkernelR

sem_t* sem_open (const char* name, int oflag, ...)

Parameters name points to a string naming a semaphore object.

oflag is the flag that controls the semaphore creation.

Returns Returns a pointer to the created/existing semaphore identifier.

Returns SEM_FAILED on failures.

Description The sem_open() function establishes a connection between a named semaphore and a process. Following a call to sem_open() with semaphore name name, the process may reference the semaphore associated with name using the address returned from the call. This semaphore may be used in subsequent calls to sem_wait(), sem_trywait(), sem_post(), and sem_close(). The semaphore remains usable by this process until the semaphore is closed by a successful call to sem_close().

The oflag argument controls whether the semaphore is created or merely accessed by the call to sem_open(). The following flag bits may be set in oflag:

O_CREAT

This flag is used to create a semaphore if it does not already exist. If O_CREAT is set and the semaphore already exists, then O_CREAT has no effect, except as noted under O_EXCL. Otherwise, sem_open() creates a named semaphore. The O_CREAT flag requires a third and a fourth argument: mode, which is of type mode_t, and value, which is of type unsigned. The semaphore is created with an initial value of value.

After the semaphore named name has been created by sem_open() with the O_CREAT flag, other processes can connect to the semaphore by calling sem_open() with the same value of name.

O_EXCL

If O_EXCL and O_CREAT are set, sem_open() fails if the semaphore name exists. The check for the existence of the semaphore and the creation of the semaphore if it does not exist are atomic with respect to other processes executing sem_open() with O_EXCL and O_CREAT set. If O_EXCL is set and O_CREAT is not set, the effect is undefined.

If flags other than O_CREAT and O_EXCL are specified in the oflag parameter, an error is signalled.

If a process makes multiple successful calls to sem_open() with the same value for name, the same semaphore address is returned for each such successful call, provided that there have been no calls to sem_unlink() for this semaphore.

Note: The mode argument is unused currently.

Includes semaphore.h

Page 55: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 55UG114 (v3.0) June 22, 2004 1-800-255-7778

Xilkernel APIR

Message QueuesXilkernel supports kernel allocated XSI message queues. XSI is the X/Open System Interface which is a set of optional interfaces under POSIX. Message queues can be used as an IPC mechanism. The message queues can take in arbitrary sized messages. However, buffer memory allocation must be configured appropriately for the memory blocks required for the messages, as a part of system malloc initialization.The number of message queue structures allocated in the kernel and the length of the message queues can be also be configured during system initialization. The message queue module is optional and can be configured in/out. Refer to the “Customizing Message Queue” section for more details. This module depends on the semaphore module and the dynamic block memory

int sem_close (sem_t* sem)

Parameters sem is the semaphore identifier

Returns Returns 0 on success.

Returns -1 on failure.

Description The sem_close() function indicates that the calling process is finished using the named semaphore sem. The sem_close() function deallocates (that is, make available for reuse by a subsequent sem_open() by this process) any system resources allocated by the system for use by this process for this semaphore. The effect of subsequent use of the semaphore indicated by sem by this process is undefined. The name mapping for this named semaphore is also destroyed. The call fails if the semaphore is currently locked.

Includes semaphore.h

int sem_unlink (const char* name)

Parameters name is the name that refers to the semaphore

Returns Returns 0 on success.

Returns -1 on failure.

Description The sem_unlink() function removes the semaphore named by the string name. If the semaphore named by name has processes blocked on it, then sem_unlink() has no immediate effect on the state of the semaphore. The destruction of the semaphore is postponed until all blocked and locking processes relinquish the semaphore. Calls to sem_open() to recreate or reconnect to the semaphore refer to a new semaphore after sem_unlink() is called. The sem_unlink() call does not block until all references relinquish the semaphore; it returns immediately.

Note: If an unlink operation had been requested on the semaphore, the unlink is performed on a post operation that sees that no more processes waiting on the semaphore.

Includes semaphore.h

Page 56: Edk Libs Ref Guide

56 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 5: XilkernelR

allocation module being present in the system. The Xilkernel message queue interface is described below.

int msgget( key_t key, int msgflg )

Parameters key is a unique identifier for referring to the message queue.

msgflg specifies the message queue creation options.

Returns Returns a unique non-negative integer message queue identifier.

Returns -1 on failure.

Description The msgget() function returns the message queue identifier associated with the argument key. A message queue identifier, associated message queue, and data structure (see <sys/kmsg.h>), are created for the argument key if the argument key does not already have a message queue identifier associated with it, and (msgflg & IPC_CREAT) is non-zero.

Upon creation, the data structure associated with the new message queue identifier is initialized as follows:

� msg_qnum, msg_lspid, msg_lrpid are set equal to 0.

� msg_qbytes is set equal to the system limit (MSGQ_MAX_BYTES).

The msgget() function fails if a message queue identifier exists for the argument key but ((msgflg & IPC_CREAT) && (msgflg & IPC_EXCL)) is non-zero.

Note: IPC_PRIVATE is not supported. Also, messages in the message queue are not required to be of the form shown below. There is no support for message type based message receives and sends in this implementation.

struct mymsg { long mtype; /* Message type. */ char mtext[some_size]; /* Message text. */}

Includes sys/msg.h

sys/ipc.h

Page 57: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 57UG114 (v3.0) June 22, 2004 1-800-255-7778

Xilkernel APIR

int msgctl (int msqid, int cmd, struct msqid_ds* buf)

Parameters msqid is the message queue identifier.

cmd is the command.

buf is the data buffer

Returns Returns 0 on success. Status is returned in buf for IPC_STAT

Returns -1 on failure.

Description The msgctl() function provides message control operations as specified by cmd. The following values for cmd, and the message control operations they specify, are:

IPC_STAT

Place the current value of each member of the msqid_ds data structure associated with msqid into the structure pointed to by buf. The contents of this structure are defined in <sys/msg.h>.

IPC_SET - Unsupported.

IPC_RMID

Remove the message queue identifier specified by msqid from the system and destroy the message queue and msqid_ds data structure associated with it. The remove operation forcibly destroys the semaphores used internally and unblocks processes that are blocked on the semaphore. It also deallocates memory allocated for the messages in the queue.

Includes sys/msg.h

sys/ipc.h

Page 58: Edk Libs Ref Guide

58 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 5: XilkernelR

int msgsnd (int msqid, const void *msgp, size_t msgsz, int msgflg)

Parameters msqid is the message queue identifier.

msgp is a pointer to the message buffer.

nbytes is the size of the message

msgflg is used to specify message send options.

Returns Returns 0 on success.

Returns -1 on failure.

Description The msgsnd() function sends a message to the queue associated with the message queue identifier specified by msqid.

The argument msgflg specifies the action to be taken if the message queue is full:

If (msgflg & IPC_NOWAIT) is non-zero, the message is not sent and the calling thread returns immediately.

If (msgflg & IPC_NOWAIT) is 0, the calling thread suspends execution until one of the following occurs:

� The condition responsible for the suspension no longer exists, in which case the message is sent.

� The message queue identifier msqid is removed from the system; when this occurs -1 is returned.

The send fails if it is unable to allocate memory to store the message inside the kernel. On a successful send operation, the msg_lspid and msg_qnum members of the message queues are appropriately set.

Includes sys/msg.h

sys/ipc.h

Page 59: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 59UG114 (v3.0) June 22, 2004 1-800-255-7778

Xilkernel APIR

Shared MemoryXilkernel supports kernel allocated XSI shared memory. XSI is the X/Open System Interface which is a set of optional interfaces under POSIX. Shared memory is a common, low-latency IPC mechanism. Shared memory blocks required during run-time must be identified and specified during the system configuration.From this specification, buffer memory is allocated to each shared memory region. Shared memory is currently not allocated dynamically at run-time. This module is optional and can be configured in or out during system specification. Refer to the “Customizing Shared Memory” section for more details. The Xilkernel shared memory interface is described below.

ssize_t msgrcv (int msqid, void *msgp, size_t nbytes, long msgtyp, int msgflg

Parameters msqid is the message queue identifier.

msgp is the buffer where the received message is to be copied.

nbytes specifies the size of the message that the buffer can hold.

msgtyp is unsupported currently.

msgflg is used to control the message receive operation.

Returns Returns 0 on success and stores received message in user buffer.

Returns -1 on failure.

Description The msgrcv() function reads a message from the queue associated with the message queue identifier specified by msqid and places it in the user-defined buffer pointed to by msgp.

The argument msgsz specifies the size in bytes of the message. The received message is truncated to msgsz bytes if it is larger than msgsz and (msgflg & MSG_NOERROR) is non-zero. The truncated part of the message is lost and no indication of the truncation is given to the calling process. If MSG_NOERROR is not specified and the received message is larger than nbytes, -1 is returned signalling error.

The argument msgflg specifies the action to be taken if a message is not on the queue. These are as follows:

If (msgflg & IPC_NOWAIT) is non-zero, the calling thread returns immediately with a return value of -1.

If (msgflg & IPC_NOWAIT) is 0, the calling thread suspends execution until one of the following occurs:

� A message is placed on the queue.� The message queue identifier msqid is removed from the

system; when this occurs -1 is returned.

Upon successful completion, the following actions are taken with respect to the data structure associated with msqid:

� msg_qnum is decremented by 1.� msg_lrpid is set equal to the process ID of the calling process.

Includes sys/msg.h

sys/ipc.h

Page 60: Edk Libs Ref Guide

60 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 5: XilkernelR

Caution! The memory buffers allocated by the shared memory API might not be aligned at word boundaries. Therefore, structures should not be arbitrarily mapped to shared memory segments, without checking if alignment requirements are met.

int shmget (key_t key, size_t size, int shmflg)

Parameters key is used to uniquely identify the shared memory region.

size is the requested size of the shared memory segment

shmflg is used to specify segment creation options

Returns Returns unique non-negative shared memory identifier on success.

Returns -1 on failure.

Description The shmget() function returns the shared memory identifier associated with key.

A shared memory identifier, associated data structure, and shared memory segment of at least size bytes (see <sys/shm.h>) are created for key if one of the following is true:

� The argument key is equal to IPC_PRIVATE.� The argument key does not already have a shared memory

identifier associated with it and (shmflg &IPC_CREAT) is non-zero.

Upon creation, the data structure associated with the new shared memory identifier shall be initialized.The value of shm_segsz is set equal to the value of size.The values of shm_lpid, shm_nattch, shm_cpid are all initialized appropriately.When the shared memory segment is created, it is initialized with all zero values

Note: At least one of the shared memory segments available in the system must EXACTLY match the requested size for the call to succeed. key IPC_PRIVATE is not supported.

Includes sys/shm.h

sys/ipc.h

Page 61: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 61UG114 (v3.0) June 22, 2004 1-800-255-7778

Xilkernel APIR

int shmctl (int shmid, int cmd, struct shmid_ds *buf)

Parameters shmid is the shared memory segment identifier.

cmd is the command to the control function.

buf is the buffer where the status is returned.

Returns Returns 0 on success. Status is returned in buffer for IPC_STAT.

Returns -1 on failure.

Description The shmctl() function provides a variety of shared memory control operations as specified by cmd. The following values for cmd are available:

IPC_STAT

Place the current value of each member of the shmid_ds data structure associated with shmid into the structure pointed to by buf. The contents of the structure are defined in <sys/shm.h>

IPC_SET is not supported

IPC_RMID

Remove the shared memory identifier specified by shmid from the system and destroy the shared memory segment and shmid_ds data structure associated with it. No notification is sent to processes still attached to the segment.

Includes sys/shm.h

sys/ipc.h

void* shmat (int shmid, const void *shmaddr, int flag)

Parameters shmid is the shared memory segment identifier.

shmaddr is used to specify the location, to attach shared memory segment. This is unused currently.

flag is used to specify SHM attach options.

Returns Returns the start address of the shared memory segment on success.

Returns NULL on failure.

Description shmat() increments the value of shm_nattch in the data structure associated with the shared memory ID of the attached shared memory segment and returns the segment’s start address. shm_lpid is also appropriately set.

Note: shmaddr and flag arguments are not used.

Includes sys/shm.h

sys/ipc.h

Page 62: Edk Libs Ref Guide

62 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 5: XilkernelR

Mutex LocksXilkernel provides support for kernel allocated POSIX thread mutex locks. This synchronization mechanism can be used alongside of the pthread_ API. The number of mutex locks and the length of the mutex lock wait queue can be configured during system

int shm_dt (void *shmaddr)

Parameters shmaddr is the shared memory segment address that is to be detached.

Returns Returns 0 on success.

Returns -1 on failure.

Description The shmdt() function detaches the shared memory segment located at the address specified by shmaddr from the address space of the calling process.The value of shm_nattch is also decremented.The memory segment is not removed from the system and can be attached to again.

Includes sys/shm.h

sys/ipc.h

Page 63: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 63UG114 (v3.0) June 22, 2004 1-800-255-7778

Xilkernel APIR

specification. This module is also optional and can be configured in or out during system specification. Please refer to the “Customizing Shared Memory”section for more details.

int pthread_mutex_init (pthread_mutex_t* mutex, const pthread_mutexattr_t* attr)

Parameters mutex is the location where the newly created mutex lock’s identifier is to be stored.

attr is the mutex creation attributes structure.

Returns Returns 0 on success and mutex identifier in *mutex.

Returns EAGAIN if system out of resources.

Description The pthread_mutex_init() function initializes the mutex referenced by mutex with attributes specified by attr. If attr is NULL, the default mutex attributes are used; the effect shall be the same as passing the address of a default mutex attributes object. Upon successful initialization, the state of the mutex becomes initialized and unlocked. Only mutex itself may be used for performing synchronization. The result of referring to copies of mutex in calls to pthread_mutex_lock(), pthread_mutex_trylock(), pthread_mutex_unlock(), and pthread_mutex_destroy() is undefined.

Attempting to initialize an already initialized mutex results in undefined behavior.In cases where default mutex attributes are appropriate, the macro PTHREAD_MUTEX_INITIALIZER can be used to initialize mutexes that are statically allocated. The effect shall be equivalent to dynamic initialization by a call to pthread_mutex_init() with parameter attr specified as NULL, except that no error checks are performed.

For example,

static pthread_mutex_t foo_mutex = PTHREAD_MUTEX_INITIALIZER;

Note: The mutex locks allocated by xilkernel follow the semantics of PTHREAD_MUTEX_DEFAULT mutex locks. i.e attempting to recursively lock the mutex results in undefined behavior. Attempting to unlock the mutex if it was not locked by the calling thread results in undefined behavior. Attempting to unlock the mutex if it is not locked results in undefined behavior.

Includes pthread.h

Page 64: Edk Libs Ref Guide

64 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 5: XilkernelR

int pthread_mutex_destroy (pthread_mutex_t* mutex)

Parameters mutex is the mutex identifier.

Returns Returns 0 on success.

Returns EINVAL if mutex refers to an invalid identifier.

Description The pthread_mutex_destroy() function destroys the mutex object referenced by mutex; the mutex object becomes, in effect, uninitialized. A destroyed mutex object can be reinitialized using pthread_mutex_init(); the results of otherwise referencing the object after it has been destroyed are undefined.

Note: Mutex lock/unlock state disregarded during destroy. No consideration is given for waiting processes.

Includes pthread.h

int pthread_mutex_lock (pthread_mutex_t* mutex)

Parameters mutex is the mutex identifier.

Returns Returns 0 on success and mutex in a locked state.

Returns EINVAL on invalid mutex reference and -1 on unhandled errors.

Description The mutex object referenced by mutex is locked by the thread calling pthread_mutex_lock(). If the mutex is already locked, the calling thread blocks until the mutex becomes available. This operation returns with the mutex object referenced by mutex in the locked state.

Includes pthread.h

int pthread_mutex_trylock (pthread_mutex_t* mutex)

Parameters mutex is the mutex identifier.

Returns Returns 0 on success and mutex in a locked state.

Returns EINVAL on invalid mutex reference, EBUSY if mutex is already locked and -1 on unhandled errors.

Description The mutex object referenced by mutex is locked by the thread calling pthread_mutex_trlock(). If the mutex is already locked, the calling thread returns immediately with EBUSY. Otherwise, the mutex is locked on behalf of the calling thread becomes available.

Includes pthread.h

Page 65: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 65UG114 (v3.0) June 22, 2004 1-800-255-7778

Xilkernel APIR

Dynamic Block Memory ManagementThe kernel provides a simple block memory allocation scheme, which can be used by applications that need dynamic memory allocation. The application can also use the standard ‘C’ memory allocation routines.The user can select different memory blocks sizes and number of such memory blocks required for the application. The memory blocks and the total memory needed by the system is allocated statically and can be configured by the user. Refer to the “Customizing Dynamic Block Memory Management” section for more details.This method of buffer management is relatively simple, small and a fast way of

int pthread_mutex_unlock (pthread_mutex_t* mutex)

Parameters mutex is the mutex identifier.

Returns Returns 0 on success.

Returns EINVAL on invalid mutex reference and -1 on undefined errors.

Description The pthread_mutex_unlock() function shall release the mutex object referenced by mutex. If there are threads blocked on the mutex object referenced by mutex when pthread_mutex_unlock() is called, resulting in the mutex becoming available, the scheduling policy shall determine which thread shall acquire the mutex. If it is SCHED_RR, then the thread that is at the head of the mutex wait queue is unblocked and allowed to lock the mutex.

Includes pthread.h

int pthread_mutexattr_init (pthread_mutexattr_t* attr)

Parameters attr is the location of the attributes structure.

Returns Returns 0 on success.

Returns EINVAL if attr refers to an invalid location.

Description The pthread_mutexattr_init() function initializes a mutex attributes object attr with the default value for all of the attributes defined by the implementation.

Note: Refer to <sys/types.h> for the contents of the pthread_mutexattr structure.This routine does not involve a call into the kernel.

Includes pthread.h

int pthread_mutexattr_destroy (pthread_mutexattr_t* attr)

Parameters attr is the location of the attributes structure.

Returns Returns 0 on success.

Returns EINVAL if attr refers to an invalid location.

Description The pthread_mutexattr_destroy() function destroys a mutex attributes object; the object becomes, in effect, uninitialized.

Note: This routine does not involve a call into the kernel.

Includes pthread.h

Page 66: Edk Libs Ref Guide

66 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 5: XilkernelR

allocating memory. The following are the block memory allocation interfaces. This module is optional and can be included during system initialization.

Caution! The memory buffers allocated by the block memory allocation API might not be aligned at word boundaries. Therefore, structures should not be arbitrarily mapped to memory allocated this way, without checking if alignment requirements are ment.

Interrupt HandlingXilkernel abstracts away the basic interrupt handling requirements of the kernel during initialization. Even though the kernel will be functional without any interrupts, it makes sense for the system to be at least driven by a single timer pulse for scheduling. In this case the kernel handles the main timer interrupt, using it as the kernel tick to perform scheduling. The timer interrupt is initialized and tied to the vectoring code during system initialization. For MicroBlaze xilkernels, the system specification requires that a timer device specification is present. MicroBlaze systems must use either the standard Xilinx FIT or PIT timers. The timer tick interval can be customized by the user based on the

void* bufmalloc (unsigned int size)

Parameters size is the size of memory block requested.

Returns Returns the start address of the memory block on success.

Return NULL on failure.

Description Allocate memory to the user process

Includes sys/mem.h

void buffree (void* mem)

Parameters mem is the address of the memory block.

Returns None

Description Free the memory allocated by bufmalloc.

Includes sys/mem.h

Page 67: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 67UG114 (v3.0) June 22, 2004 1-800-255-7778

Interrupt HandlingR

application if the PIT is used in MicroBlaze systems and always, in PPC405 systems. Refer to the “Configuring System Timer” section for more details.

The interrupt service in this scenario with a single timer interrupt in the system is sketched in Figure 5-6. Upon an interrupt, the volatile registers (defined by the EABI of the processor) are saved onto the interrupted task’s stack. The interrupt is then vectored to a handler that is registered at system startup. In Xilkernel’s case, the timer_int_handler() routine, is the registered handler. This routine invokes process_scheduler() to request a rescheduling operation. If the reschedule operation switched tasks, a context switch is performed. If a programmable interval timer is present in the system (always present in PPC) then its counter is reset to the interval defined at system startup. After the context switch, execution will resume in the context of the switched-to process. Since volatile registers were saved on the stack during an interrupt, they are again restored appropriately from the stack of whatever process gets to execute.

Xilkernel can also work with multiple interrupts in the system, handled through an interrupt controller. See the “Configuring Interrupt Handling” section for more details on configuring Xilkernel for multiple external interrupt handling. Figure 5-7 illustrates the service sequence when interrupts are handled through an interrupt controller. The interrupt controller’s handler services all interrupt requests. However, the timer_int_handler() does not immediately perform a context switch, in this configuration. It sets a flag indicating if a context switch is required. The interrupt controller’s handler recognizes a pending context switch and performs the actual context switch at the end of the service routine. The rest of the flow is similar to the basic service routine. The flow is slightly different from PPC systems, since there is a dedicated interrupt notification for the internal PIT device. In other words, the handlers for the system timer interrupt and other external interrupts are different and hence the interrupt controller’s handler follows this

Figure 5-6: Basic Interrupt Service in Xilkernel

Interrupts/ExceptionsEnabled

Interrupts/ExceptionsDisabled

Save volatile registersinterrupt vectoring code

Task CodeInterrupted

X10141

Interrupts/ExceptionsEnabled

Restore volatile registers

Next TaskProceeds

timer_int_handler( )process_scheduler( );IF context switch required THENXMK_CONTEXT_SWITCH( );

Return in the contextof the "next" task

Page 68: Edk Libs Ref Guide

68 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 5: XilkernelR

sequence of actions, without the scheduling portion, while the timer_int_handler() performs the same sequence of actions as the basic service routine.

There are certain limitations on the operations that can be performed inside the user-level interrupt handlers. Since, technically, the system is still executing the ISR in the context of the task that was interrupted, invoking any kind of API that may cause a rescheduling operation can potentially cause the system to enter an invalid state. The advantage of letting the system still be in the context of the process that was interrupted, in an ISR, is that on an interrupt, the entire context of the process need not be saved. This can provide significant reduction in the actual interrupt service response time. However, it imposes the restriction described above. The actual context switch, due to a rescheduling operation by the kernel, occurs at the end of servicing all the ISRs.

Xilkernel support for multiple interrupts has been designed to work with the opb_intc peripheral that is a part of the standard EDK distribution. Other interrupt controllers will need the relevant support routines in the mb-hw.c, ppc-hw.c and the intr.c,h files, modified accordingly. Xilkernel also recognizes only interrupts connected through only one level of

Figure 5-7: Extended Interrupt Service in Xilkernel

IE = 1

IE = 1

IE = 0_ _interrupt_handler( )save volatile registersintc_device_interrupt_handler( );

Task CodeGetsInterrupted

X10140

IE = 1Restore saved registers

Next TaskProceeds

intc_device_interrupt_handler( )1. Determine source of interrupts2. Service ALL interrupt requests3. IF process_scheduler( ) invoked on

a timer interrupt THENDo a context switch if required

Return in the contextof the "next" task

Page 69: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 69UG114 (v3.0) June 22, 2004 1-800-255-7778

Interrupt HandlingR

interrupt controllers. Cascaded interrupt controllers are not supported. The Xilkernel user-level interrupt handling API, is described below.

unsigned int register_int_handler (int_id_t id, void (*handler)(void*), void *callback)

Parameters id is the zero-based numeric id of the interrupt.

handler is the user-level handler.

callback is a callback value that can be delivered to the user-level handler.

Returns Returns XST_SUCCESS on success.

Returns error codes defined in <xstatus.h>.

Description The register_int_handler() function registers the specified user level interrupt handler as the handler for a specified interrupt. The user level routine will be invoked asynchronously upon being serviced by an interrupt controller in the system. The routine returns an error on MicroBlaze systems, if id is the identifier for the system timer interrupt. PPC systems have a dedicated hardware timer interrupt that exists separately from the other interrupts in the system. Therefore, this check is not performed for a PPC system.

Includes <sys/intr.h>

void unregister_int_handler (int_id_t id)

Parameters id is the zero-based numeric id of the interrupt.

Returns None

Description The unregister_int_handler() function unregisters the registered user level interrupt handler as the handler for the specified interrupt. The routine does nothing and fails silently on MicroBlaze systems, if id is the identifier for the system timer interrupt.

Includes <sys/intr.h>

void enable_interrupt (int_id_t id)

Parameters id is the zero-based numeric id of the interrupt.

Returns None

Description The enable_interrupt() function enables the specified interrupt in the interrupt controller. The routine does nothing and fails silently on MicroBlaze systems, if id is the identifier for the system timer interrupt.

Includes <sys/intr.h>

Page 70: Edk Libs Ref Guide

70 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 5: XilkernelR

Kernel CustomizationXilkernel is highly customizable. As described in previous sections, modules and individual parameters can be changed to suit the user application. The XPS GUI system provides excellent support for easy configuration of parameters of Xilkernel, using the software platform settings dialog. Refer to Chapter 2, “Xilinx Platform Studio (XPS)” in the Embedded Systems Tools Guide for more details. In order to customize a module in the kernel, a parameter with the name of the category set to true must be defined in the MSS. For example, to customize the pthread module,

parameter config_pthread_support = true

is required in the OS specification. Not defining a configurable module’s config_ parameter will mean that the module will be configured out.

An MSS snippet for configuring OS Xilkernel for a PPC system is given below:

PARAMETER os_name = xilkernel PARAMETER os_ver = 2.00.a PARAMETER stdin = RS232 PARAMETER stdout = RS232 PARAMETER proc_instance = ppc405_0 PARAMETER linker_script_specification = true PARAMETER vec_mem_start = 0xffff0000 PARAMETER vec_mem_size = 16k PARAMETER data_mem_start = 0xffff4000 PARAMETER data_mem_size = 20k PARAMETER code_mem_start = 0xffff9000 PARAMETER code_mem_size = 28k PARAMETER config_process = true PARAMETER sched_type = 2 PARAMETER config_shm = true PARAMETER shm_table = (100)

void disable_interrupt (int_id_t id)

Parameters id is the zero-based numeric id of the interrupt.

Returns None

Description The disable_interrupt() function disables the specified interrupt in the interrupt controller. The routine does nothing and fails silently on MicroBlaze systems, if id is the identifier for the system timer interrupt.

Includes <sys/intr.h>

void acknowledge_interrupt (int_id_t id)

Parameters id is the zero-based numeric id of the interrupt.

Returns None

Description The acknowledge_interrupt() function acknowledges handling the specified interrupt to the interrupt controller. The routine does nothing and fails silently on MicroBlaze systems, if id is the identifier for the system timer interrupt.

Includes <sys/intr.h>

Page 71: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 71UG114 (v3.0) June 22, 2004 1-800-255-7778

Kernel CustomizationR

PARAMETER config_msgq = true PARAMETER msgq_capacity = 5

PARAMETER config_sema = true PARAMETER multi_elf_process_table = ((0xf8000000,31)) PARAMETER max_procs = 5 PARAMETER max_readyq = 5 PARAMETER config_pthread_support = true

PARAMETER max_pthreads = 5PARAMETER config_pthread_mutex = truePARAMETER config_malloc = truePARAMETER mem_table = ((4,10), (3,10),(8,10)) PARAMETER pit_interval = 0xffffffPARAMETER copyoutfiles = truePARAMETER copyfromdir = .PARAMETER copytodir = /usr/kernelsrc

end

The values in the snippet show above are only sample values, targeting a hypothetical board. The configuration directives in the MSS specification have the corresponding implication on memory and code size of the resultant Xilkernel image. This is especially true for kernel allocated structures, whose count can be configured through the MSS. For e.g. The maximum number of process context structures allocated in the kernel is determined by the sum of two parameters; max_procs and max_pthreads. If a process context structures occupies x bytes of bss memory, then the total bss memory requirement for process contexts will be (max_procs + max_pthreads)*x bytes. Therefore, such parameters should be carefully tuned, and the final kernel image should be examined with the GNU size utility to make sure that memory requirements are met. To get an idea of the contribution of each kernel allocated structures memory requirements, please take a look at the corresponding header file. The specification in the MSS gets translated by libgen and the Xilkernel TCL files into C-language configuration directives in two header files - os_config.h and config_init.h. Interested users should take a look at these two files, which are generated in the main processor include directory, to get an idea of how the specification gets translated.

Customizing STDIN and STDOUTThe standard input and output peripherals can be configured for Xilkernel. Xilkernel can work without a standard input and output too. These peripherals are the targets of input-output API like print, outbyte, inbyte etc.

Table 5-1: STDIN/STDOUT configuration parameters

Customizing User Initialization RoutineA user initialization routine can be optionally invoked as a part of Xilkernel initialization with this parameter. The routine must be named as user_init. Note that the user_init routine should be present within the symbolic scope of the kernel. Therefore, it can be a

Attribute Description Type Defaults

stdin Instance name of stdin peripheral string none

stdout Instance name of stdout peripheral string none

Page 72: Edk Libs Ref Guide

72 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 5: XilkernelR

part of an application that is in the kernel bundle mode. If there are no kernel bundle applications, then it should be in one of the compiled kernel sources.

Table 5-2: User initialization routine parameters

Customizing Process ManagementThe user can select the maximum number of processes in the system and the different functions needed to handle processes. The processes and threads that are present in the system on system startup can be configured statically.

Attribute Description Type Defaults

user_init Invoke user_init during system initialization. boolean false

Table 5-3: Process management parameters

Attribute Description Type Defaults

config_process Need process management boolean true

max_procs Maximum number of processes in the system numeric 10

max_readyq Maximum size of Ready queue for each priority numeric 10

config_process_kill Include process_kill() function boolean false

config_process_kill Include process_kill() function boolean false

config_process_sleep Include process_sleep() function boolean false

separate_exec_process_table Configure startup processes that are separate executable files. This is defined to be an array with each element containing the parameters process_start and process_prio.

array of 2-tuples none

kernel_bundled_process_table Configure startup processes that are a part of the kernel bundle. This is defined to be an array with each element containing the parameters process_start_func, process_prio, and process_stack_size.

array of 3-tuples none

process_start Process start address address none

process_start_func Process start function string none

process_prio Process priority numeric none

process_stack_size Size of the process’s stack numeric none

Page 73: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 73UG114 (v3.0) June 22, 2004 1-800-255-7778

Kernel CustomizationR

Customizing SchedulingThe user can configure the type of scheduler used and the number of priorities used for the Scheduler module. The configurable parameters are given below.

Customizing Thread ManagementThe user can optionally select to include thread support, the maximum number of threads and size of the thread stack etc. The configurable parameters are given below.

Table 5-4: Scheduling parameters

Attribute Description Type Defaults

config_sched Configure scheduler module boolean true

sched_type Type of Scheduler to be used. Allowed values

� 2 - SCHED_RR� 3 - SCHED_PRIO

numeric 2 (SCHED_RR)

n_prio Number of priority levels if scheduling is SCHED_PRIO.

numeric 32

Table 5-5: Thread module parameters

Attribute Description Type Defaults

config_pthread_support Need pthread module boolean false

max_pthreads Maximum number of threads numeric 5

pthread_stack_size Stack size for dynamically created threads (in bytes) numeric 600

separate_exec_pthread_table Configure startup threads that are also separate executable files. This is defined to be an array with each element containing the parameters pthread_start and pthread_prio.

array of 2-tuples none

kernel_bundled_pthread_table Configure startup threads that are a part of the kernel bundle. This is defined to be an array with each element containing the parameters pthread_start_func and pthread_prio.

array of 2-tuples none

pthread_start Thread start address address none

Page 74: Edk Libs Ref Guide

74 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 5: XilkernelR

Customizing SemaphoreThe user can optionally select to include semaphores, maximum number of semaphores and semaphore queue length. The following are the parameters used for configuration.

Customizing Message QueueThe user can optionally select to include message queue module, number of message queues and the size of each message queue. The message queue module depends on both the semaphore module and the malloc module.The following parameters definitions are used for configuration. Memory for messages must be explicitly specified in the malloc customization.

Customizing Shared MemoryThe user can optionally select to include shared memory and size of each shared memory segment. All the shared memory segments that will ever be needed must be specified in these parameters.The following parameters are used for configuration.

pthread_start_func Thread start function string none

process_prio Thread priority numeric none

Table 5-5: Thread module parameters

Attribute Description Type Defaults

Table 5-6: Semaphore module parameters

Attribute Description Type Defaults

config_sema Need Semaphore module boolean false

max_sem Maximum number of Semaphores numeric 10

max_sem_waitq Semaphore Wait Queue Length numeric 10

Table 5-7: Message queue module parameters

Attribute Description Type Defaults

config_msgq Need Message Queue module boolean false

num_msgqs Number of message queues in the system numeric 10

msgq_capacity Maximum number of messages in the queue numeric 10

Page 75: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 75UG114 (v3.0) June 22, 2004 1-800-255-7778

Kernel CustomizationR

Table 5-8: Shared Memory Module Parameters

Customizing Pthread MutexThe user can optionally select to include the pthread mutex module, number of mutex locks and the size of the wait queue for the mutex locks.The following parameter are used for configuration.

Customizing Dynamic Block Memory ManagementThe user can optionally select to include the dynamic block memory management module, size of memory blocks and number of memory blocks. The following parameters are used for configuration.

Attribute Description Type Defaults

config_shm Need Shared Memory module boolean false

shm_table Shared Memory table. This is defined as an array with each element having shm_size parameter

array of 1-tuples none

shm_size Shared Memory size numeric none

num_shm Number of Shared Memories - Size of the shm_table array. numeric none

Table 5-9: Pthread mutex Module Parameters

Attribute Description Type Defaults

config_pthread_mutex Need pthread mutex module boolean false

max_pthread_mutex Maximum number of pthread mutex locks available in the system.

numeric 5

max_pthread_mutex_ waitq Length of each the mutex lock wait queue.

numeric 10

Table 5-10: Memory Management module parameters

Attribute Description Type Defaults

config_malloc Need Memory Management boolean false

mem_table Memory block table. This is defined as an array with each element having mem_bsize, mem_nblks parameters.

array of 2-tuples none

mem_bsize Memory block size. numeric none

Page 76: Edk Libs Ref Guide

76 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 5: XilkernelR

Customizing Linker Script (PPC405)Building Xilkernel for PPC requires a linker script to specify the location of the vectors section in the image. The user can customize the default linker script (linker_include.sh and linker_script.sh) files for building PowerPC kernel. If configuring, the user must specify the start address and size of three program sections - vector table, code section and data section. The following parameters are used for configuration.

mem_nblks Number of memory blocks of a size numeric none

n_malloc_blocks Number of memory blocks configurations - Size of mem_table array

numeric none

Table 5-10: Memory Management module parameters

Attribute Description Type Defaults

Table 5-11: Linker Script Configuration parameters in PPC405

Attribute Description Type Defaults

linker_script_specification Need Custom Linker Script specification boolean false

vect_mem_start Start address of Vector Table Program section. address 0x0

vect_mem_size Size of Vector table section. Specify as xK.

numeric-size 9K

code_mem_start Start address of Code section. address 0xffffd000

code_mem_size Size of Code section. Specify as xK.

numeric-size 12K

data_mem_start Start address of Data section. address 0x2400

data_mem_size Size of Data section. Specify as xK.

numeric-size 9K

Page 77: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 77UG114 (v3.0) June 22, 2004 1-800-255-7778

Kernel CustomizationR

Configuring System TimerThe user can configure the timer device in the system for MicroBlaze kernels. Additionally, he can configure the timer interval for PPC and for MicroBlaze, if the MicroBlaze system includes a PIT timer. The following parameters are used.

Configuring Interrupt HandlingThe user can configure the interrupt controller device in the system kernels. Adding this parameter, automatically configures multiple interrupt support and the user-level interrupt handling API in the kernel. The following parameters are used.

Configuring Debug MessagesThe user can configure that the kernel outputs debug/diagnostic messages through its execution flow. Enabling the following parameters makes available the DBG_PRINT macro and subsequently its output to the standard output device.

Table 5-12: Attributes for Copying Kernel Source Files

Attribute Description Type Defaults

systmr_spec (MicroBlaze only)

A tuple specifying the timer device instance name and the timer type. For example, (system_timer, PIT). PIT and FIT are the only supported timer type strings.

2-tuple of (string, string) null

pit_interval Specify the count down interval for the PIT timer in PPC and the PIT timer in MicroBlaze, if so configured.

numeric 0xffffff

Table 5-13: Attributes for Copying Kernel Source files

Attribute Description Type Defaults

sysintc_spec Specify the instance name of the interrupt controller device connected to the external interrupt port.

string null

Attribute Description Type Defaults

debug_mode Turn on debug messages from the kernel. boolean false

Page 78: Edk Libs Ref Guide

78 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 5: XilkernelR

Copy Kernel Source FilesThe user can copy the configured kernel source files to his repository for further editing and using them for building the kernel. The following parameters are used.

Debugging XilkernelIn kernel bundled executable mode, there is a single file that can serve as the target for debugging. Therefore all kernel bundled user applications can be debugged together using GDB. However this is not the case for separate executable mode. Therefore, separate executable applications can currently, not be debugged with XMD and GDB.

Memory FootprintThe size of Xilkernel depends on the user configuration. It is small in size and can fit in different configurations. The following is the memory size output from GNU size utility for the kernel. The image for the PPC version of Xilkernel includes the code for the exception and interrupt vectors, which is by design entitled to occupy 8 Kb of text space. Therefore the text sizes reported below include this 8 Kb of vector code space. Xilkernel has been tested with the GCC optimization flag of -O2, These numbers below are also from the same optimization level.

Table 5-14: Attributes for Copying Kernel Source files

Attribute Description Type Defaults

copyoutfiles Need to Copy source files boolean false

copyfromdir The Kernel source directory path. The path is relative to <project_direc>/<systemname>/libsrc/xilkernel_v2_00_a/src directory

path string “.”

copytodir User repository directory. The path is relative to <project_direc>/<systemname>/libsrc/xilkernel_v2_00_a/src directory

path string "../../../copyoflib"

Table 5-15: User Configuration and Xilkernel Size

Configuration MicroBlaze (in Kb) PPC (in Kb)

Barebones kernel ~4.4K ~12.4

Basic kernel functionality with only multi-processing (no threads)

~4.5 ~12.5

Page 79: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 79UG114 (v3.0) June 22, 2004 1-800-255-7778

Xilkernel File OrganizationR

Xilkernel File OrganizationXilkernel sources are organized in the following manner. The root level contains the data and the src folders. The data folder contains the MLD and the TCL files, that determine the configuration of Xilkernel. The src folder contains all the sources. src has a sub-folder src, which contains non-header source files, categorized into arch, sys and ipc folders. arch contains architecture specific sources, while sys contains system-level sources. ipc contains all the sources implementing the IPC functionality. The header files are contained under the include folder of the top-level src folder. The header files are also organized in a way similar to src. There is also a test folder, that contains internal test cases that can be used to get an idea of how Xilkernel functionality can be used.

System InitializationThe entry point for the kernel is the main() routine defined in main.c. The first action performed is hardware specific initialization. This includes registering the interrupt handlers and configuring the system timer. This portion of the initialization depends upon the kind of hardware that is present in the system. Interrupts/exceptions are not enabled after completing hw_init(). If the user has required user_init() to be invoked as a part of the system initialization, then user_init() is invoked next (This applies only if the user_init routine is within the symbolic scope of the rest of the kernel). The sys_init() routine is entered next. This routine performs initialization of each module such as processes, threads, etc. Specifically, it initializes the following things, in order.

1. Internal process context structures

2. Ready queues

3. Pthread module

4. Semaphore module

5. Message Queue module

6. Shared memory module

7. Memory allocation module

8. Idle task creation

9. Static separate executable process creation

10. Static kernel bundled process creation

Basic kernel functionality with multi-tasking and multi-threading.

~7.4 ~15.7

Full kernel functionality with all modules (processes, threads, support for both separate and kernel bundled applications, IPC, synchronization constructs, malloc, interrupt handling, drivers for interrupt controller and timer)

~19.3 24.1

Table 5-15: User Configuration and Xilkernel Size

Configuration MicroBlaze (in Kb) PPC (in Kb)

Page 80: Edk Libs Ref Guide

80 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 5: XilkernelR

11. Static separate executable pthread creation

12. Static kernel bundled pthread creation

After these steps, interrupts and exceptions are enabled and the kernel loops infinitely (blocks), enabling the scheduler to start scheduling a process.

LimitationsXilkernel currently has the following limitations.

� The PPC xilkernel image size is contributed significantly (8 Kb) to by the exception vector code. In general, Xilkernel can be further optimized for size.

� Timer support is not complete in both versions of Xilkernel.

� POSIX error reporting structure is not fully complete. Therefore, the errno feature is not supported in the POSIX calls.

� There is restriction on rescheduling tasks within an interrupt handler (described in earlier sections). This means that usage of semaphores, mutex locks, message queues and creating or manipulating processes and threads cannot occur within interrupt handlers.

Future EnhancementsApart from overcoming the above limitations, future enhancements will focus on supporting the following features.

� Memory protection (with some hardware support).

� Better memory allocation and memory mapping functionality.

� Preventing priority inversion with priority inheritance.

� Supporting debugging of separate executable applications with GDB.

� Alarms and Timers.

� Migrating to POSIX scheduling schemes (SCHED_FIFO and SCHED_RR schemes in a common priority based implementation).

� POSIX signals.

Modifying XilkernelUsers can further customize Xilkernel by changing the actual code base. To work with a custom copy of Xilkernel, users first copy the Xilkernel source folder (xilkernel_v2_00_a) from within the EDK installation and place it under the bsp folder of the project folder. For example, <..../myproject/bsp/xilkernel_v2_00_a>. Libgen now picks up this source folder of Xilkernel for compilation, since it looks for Xilkernel sources first under the bsp folder before picking it up from the standard installation. Refer to “Xilkernel File Organization” for more information on the organization of the Xilkernel sources. Xilkernel sources have been written in an elementary and intuitive style and include comment blocks above each significant function. Each source file also carries a comment block indicating its role.

User GuideRefer to the “Using Xilkernel” chapter in the Platform Studio User Guide for detailed steps on configuring and using Xilkernel. Information on how to develop, build, and download

Page 81: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 81UG114 (v3.0) June 22, 2004 1-800-255-7778

User GuideR

applications is also present in that chapter. Some example systems and applications are illustrated. These design examples illustrate all the features of Xilkernel and therefore will be very useful for users who would like to quickly get started with Xilkernel.

Page 82: Edk Libs Ref Guide

82 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 5: XilkernelR

Page 83: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 83UG114 (v3.0) June 22, 2004 1-800-255-7778

R

Chapter 6

LibXil Net

This chapter describes the network library for Embedded processors, libXilNet. The library includes functions to support the TCP/IP stack and the higher level application programming interface (Socket APIs).

The chapter contains the following sections.

� “Overview”

� “LibXilNet Functions”

� “Protocols Supported”

� “Library Architecture”

� “Protocol Function Description”

� “Current Restrictions”

� “Functions of LibXilNet”

� “LibGen Customization”

� “Using XilNet in Application”

OverviewThe Embedded Development Kit (EDK) networking library, libXilNet, allows a processor to connect to the internet. LibXilNet includes functions for handling the TCP/IP stack protocols. It also provides a simple set of Sockets Application Programming Interface (APIs) functions enabling network programming. Lib Xil Net supports multiple connections (through Sockets interface) and hence enables multiple client support. This chapter describes the various functions of LibXilNet.

LibXilNet Functions

Quick GlanceTable 6-1 presents a list of functions provided by the LibXilNet at a glance.

Table 6-1: LibXilNet functions at a glance

Functions

int xilsock_init (void)

void xilsock_rel_socket (int sd)

int xilsock_socket (int domain, int type, int proto)

Page 84: Edk Libs Ref Guide

84 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 6: LibXil NetR

int xilsock_bind (int sd, struct sockaddr* addr, int addrlen)

int xilsock_listen (int sd, int backlog)

int xilsock_accept (int sd, struct sockaddr* addr, int* addrlen)

int xilsock_recvfrom (int s, unsigned char* buf, unsigned int len, struct sockaddr* from, unsigned int* fromlen)

int xilsock_sendto (int s, unsigned char* buf, int len, struct sockaddr* to, unsigned int tolen)

int xilsock_recv (int s, unsigned char* buf, unsigned int len)

int xilsock_send (int s, unsigned char* buf, unsigned int len)

void xilsock_close (int s)

void xilnet_mac_init (unsigned int baseaddr)

int xilnet_eth_find_old_entry(void)

void xilnet_eth_init_hw_addr(unsigned char *addr)

int xilnet_eth_recv_frame (unsigned char* frame, int len)

int xilnet_eth_send_frame (unsigned char* frame, int len, void* daddr, unsigned short type)

void xilnet_eth_update_hw_tbl (unsigned char* frame, int proto)

void xilnet_eth_add_hw_tbl_entry (unsigned char* ip, unsigned char* hw)

int xilnet_eth_get_hw_addr (unsigned char* ip)

int xilnet_eth_init_hw_addr_tbl (void)

int xilnet_arp (unsigned char* buf, int len)

void xilnet_arp_reply (unsigned char* buf, int len)

void xilnet_ip_init (unsigned char* ip_addr)

int xilnet_ip (unsigned char* buf, int len)

void xilnet_ip_header (unsigned char* buf, int len, int proto, unsigned char* peer_ip_addr)

unsigned short xilnet_ip_calc_chksum (unsigned char* buf, int len)

int xilnet_udp (unsigned char* buf, int len)

void xilnet_udp_header (struct xilnet_udp_conn* conn, unsigned char* buf, int len)

unsigned short xilnet_tcp_udp_calc_chksum (unsigned char* buf, int len, unsigned char* saddr, unsigned char* daddr, unsigned short proto)

Table 6-1: LibXilNet functions at a glance

Functions

Page 85: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 85UG114 (v3.0) June 22, 2004 1-800-255-7778

Protocols SupportedR

Protocols SupportedLibXilNet supports drivers and functions for the Sockets API and protocols of TCP/IP stack. The following list enumerates them.

� Ethernet Encapsulation (RFC 894)

� Address Resolution Protocol (ARP - RFC 826)

� Internet Protocol (IP - RFC 791)

� Internet Control Management Protocol (ICMP - RFC 792)

� Transmission Control Protocol (TCP - RFC 793)

� User Datagram Protocol (UDP - RFC 768)

� Sockets API

Library ArchitectureFigure 6-1 gives the architecture of libXilNet. Higher Level applications like HTTP server, TFTP (Trivial File Transfer Protocol), PING etc., uses API functions to use the libXilNet library

void xilnet_udp_init_conns (void)

int xilnet_udp_open_conn (unsigned short port)

int xilnet_udp_close_conn (struct xilnet_udp_conn* conn)

int xilnet_tcp (unsigned char* buf, int len)

void xilnet_tcp_header (struct xilnet_tcp_conn* conn, unsigned char* buf, int len, unsigned char flags)

void xilnet_tcp_send_pkt (struct xilnet_tcp_conn* conn, unsigned char* buf, int len, unsigned char flags)

void xilnet_tcp_init_conns (void)

int xilnet_tcp_open_conn (unsigned short port)

int xilnet_tcp_close_conn (struct xilnet_tcp_conn* conn)

int xilnet_icmp (unsigned char* buf, int len)

void xilnet_icmp_echo_reply (usigned char* buf, unsigned int len)

Table 6-1: LibXilNet functions at a glance

Functions

Page 86: Edk Libs Ref Guide

86 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 6: LibXil NetR

Figure 6-1: Schematic Diagram of LibXilNet Architecture

From PHY Interface

Incoming Frame

Demultiplexing based onframe type in Ethernet Header

Demultiplexing basedon protocal value inIP Header

Demultiplexingbased onconnections

TFTP ApplicationHTTP Server ApplicationPING Application

Xilinx Sockets Interface

ICMP

ARP IP

TCP UDP

EthernetDriver

MACDriver

LibXilNet Architecture

UG111_07_111903

Page 87: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 87UG114 (v3.0) June 22, 2004 1-800-255-7778

Protocol Function DescriptionR

Protocol Function DescriptionA detailed description of the drivers and the protocols supported is given below.

Media Access Layer (MAC) Drivers WrapperMAC drivers wrapper initializes the base address of the mac instance specified by the user.This base address is used to send and receive frames. This initialization must be done before using other functionalites of LibXil Net library. The details of the function prototype is defined in the section“Functions of LibXilNet.”

Ethernet DriversEthernet drivers perform the encapsulation/removal of ethernet headers on the payload in accordance with the RFC 894. Based on the type of payload (IP or ARP), the drivers call the corresponding protocol callback function. A Hardware Address Table is maintained for mapping 48-bits ethernet address to 32-bits IP address.

ARP (RFC 826)Functions are provided for handling ARP requests. An ARP request (for the 48-bit hardware address) is acknowledged with the 48-bit ethernet address in the ARP reply. Currently, ARP request generation for a desired IP address is not supported. The Hardware address table is updated with the new IP/Ethernet address pair if the ARP request is destined for the processor.

IP (RFC 791)IPv4 datagrams are used by the higher level protocols like ICMP, TCP, and UDP for receiving/sending data. A callback function is provided for ethernet drivers which is invoked whenever there is an IP datagram as a payload in an ethernet frame. Minimal processing of the source IP address check is performed before the corresponding higher level protocol (ICMP, TCP, UDP) is called. Checksum is calculated on all the outgoing IP datagrams before calling the ethernet callback function for sending the data. An IP address for a Embedded Processor needs to be programmed before using it for communication. An IP address initializing function is provided. Refer to the table describing the various routines for further details on the function. Currently no IP fragmentation is performed on the outgoing datagrams. The Hardware address table is updated with the new IP/Ethernet address pair if an IP packet was destined for the processor.

ICMP (RFC 792)ICMP functions handling only the echo requests (ping requests) are provided. Echo requests are issued as per the appropriate requirements of the RFC (Requests For Comments).

UDP (RFC 768)UDP is a connectionless protocol. The UDP callback function, called from the IP layer, performs the minimal check of source port and strips off the UDP header. It demultiplexes from the various open UDP connections. A UDP connection can be opened with a given source port number through Socket functions. Checksum calculation is performed on the

Page 88: Edk Libs Ref Guide

88 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 6: LibXil NetR

outgoing UDP datagram. The number of UDP connections that can be supported simultaneously is configurable.

TCP (RFC 793)TCP is a connection-oriented protocol. Callback functions are provided for sending and receiving TCP packets. TCP maintains connections as a finite state machine. On receiving a TCP packet, minimal check of source port correctness is done, before demultiplexing the TCP packet from the various TCP connections. Necessary action for the demultiplexed connection is taken based on the current machine state. A status flag is returned to indicate the kind of TCP packet received to support connection management. Connection management has to be done at the application level using the status flag received from TCP. Checksum is calculated on all outgoing TCP packets. The number of TCP connections that can be supported simultaneously is configurable.

Sockets APIFunctions for creating sockets (TCP/UDP), managing sockets, sending and receiving data on UDP and TCP sockets are provided. High level network applications need to use these functions for performing data communication. Refer to Table 6-1 for further details.

Buffer ManagementXiNet stack is geared to work with smaller FPGA devices and hence minimal buffer management is provided. The stack uses two global buffers - sendbuf, recvbuf - to send and receive ethernet frames. User code can either allocate a buffer or use sendbuf to send packets from the application. When sendbuf is used to transmit packets, user code is responsible to place the application data at the right offset from start of sendbuf accounting for all layers of stack starting from ethernet header.

Current Restrictions Certain restrictions apply to the EDK libXilNet library software. These are

� Only server functionalities for ARP - This means ARP requests are not being generated from the processor

� Only server functionalities in libXilNet - This means no client application development support provided in libXilNet.

� No timers in TCP - Since there are no timers used, every "send" over a TCP connection waits for an "ack" before performing the next "send".

Functions of LibXilNetThe following table gives the list of functions in libXilNet and their descriptions

Page 89: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 89UG114 (v3.0) June 22, 2004 1-800-255-7778

Functions of LibXilNetR

int xilsock_init (void)

void xilsock_rel_socket (int sd)

int xilsock_socket (int domain, int type, int proto)

int xilsock_bind (int sd, struct sockaddr* addr, int addrlen)

Parameters None

Returns 1 for success and 0 for failure

Description Initialize the xilinx internal sockets for use.

Includes xilsock.h

Parameters sd is the socket to be released.

Returns None

Description Free the system level socket given by the socket descriptor sd

Includes xilsock.h

Parameters domain: Socket Domain

type: Socket Type

proto: Protocol Family

Returns On success, return socket descriptor

On failure, return -1

Description Create a socket of type, domain and protocol proto and returns the socket descriptor. The type of sockets can be:

SOCK_STREAM (TCP socket)

SOCK_DGRAM (UDP socket)

domain value currently is AF_INET

proto refers to the protocol family which is typically the same as the domain.

Includes xilsock.h

Parameters sd: Socket descriptor

addr: Pointer to socket structure

addrlen: Size of the socket structure

Returns On success, return 1

On failure, return -1

Description Bind socket given the descriptor sd to the ip address/port number pair given in structure pointed to by addr of len addrlen. addr is the typical socket structure.

Includes xilsock.h

Page 90: Edk Libs Ref Guide

90 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 6: LibXil NetR

int xilsock_accept (int sd, struct sockaddr* addr, int *addrlen)

int xilsock_recvfrom (int s, unsigned char* buf, int len)

int xilsock_sendto (int s, unsigned char* buf, int len)

Parameters sd: Socket descriptor

addr: Pointer to socket structure

addrlen: Pointer to the size of the socket structure

Returns On success, return socket descriptor

On failure, return -1

Description Accepts new connections on socket sd. If a new connection request arrives, it creates a new socket nsd, copies properties of sd to nsd, returns nsd. If a packet arrives for an existing connection, returns 0 and sets the xilsock_status_flag global variable. The various values of the is flag are:

XILSOCK_NEW_CONN

XILSOCK_CLOSE_CONN

XILSOCK_TCP_ACK

for new connection, closed a connection and acknowledgment for data sent for a connection correspondingly.

This function implicitly polls/waits on a packet from MAC. Arguments addr and addrlen are in place to support the standard Socket accept function signature. At present, they are not used in the accept function.

Includes xilsock.h

Parameters s: UDP socket descriptor

buf: Buffer to receive data

len: Buffer size

Returns Number of bytes received

DescriptionReceives data (maximum length of len) from the UDP socket s in buf and returns the number of bytes received.

Includes xilsock.h

Parameters s: UDP socket descriptor

buf: Buffer containing data to be sent

len: Buffer size

Returns Number of bytes received

Description Sends data of length len in buf on the UDP socket s and returns the number of bytes sent.

Includes xilsock.h

Page 91: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 91UG114 (v3.0) June 22, 2004 1-800-255-7778

Functions of LibXilNetR

int xilsock_recv (int s, unsigned char* buf, int len)

int xilsock_send (int s, unsigned char* buf, int len)

void xilsock_close (int s)

void xilnet_mac_init (unsigned int baseaddr)

Parameters s: TCP socket descriptor

buf: Buffer to receive data

len: Buffer size

Returns Number of bytes received

Description Receives data (maximum length of len) from the TCP socket s in buf and returns the number of bytes received.

Includes xilsock.h

Parameters s: TCP socket descriptor

buf: Buffer containing data to be sent

len: Buffer size

Returns Number of bytes received

Description Sends data of length len in buf on the UDP socket s and returns the number of bytes sent.

Includes xilsock.h

Parameters s: socket descriptor

Returns None

Description Closes the socket connection given by the descriptor s. This function has to be called from the application for a smooth termination of the connection after a connection is done with the communication.

Includes xilsock.h

Parameters baseaddr: Base address of the MAC instance used in a system

Returns None

Description Initialize the MAC base address used in the libXil Net library to baseaddr. This function has to be called at the start of a user program with the base address used in the MHS file for ethernet before starting to use other functions of libXil Net library.

Includes mac.h

Page 92: Edk Libs Ref Guide

92 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 6: LibXil NetR

void xilnet_eth_init_hw_addr (unsigned char* addr)

int xilnet_eth_recv_frame (unsigned char* frame, int len)

void xilnet_eth_send_frame (unsigned char* frame, int len, unsigned char* dipaddr, void *dhaddr, unsigned short type)

Parameters addr: 48-bit colon separated hexa decimal ethernet address string

Returns None

Description Initialize the source ethernet address used in the libXil Net library to addr. This function has to be called at the start of a user program with a 48-bit, colon separated, hexa decimal ethernet address string for source ethernet address before starting to use other functions of libXil Net library. This address will be used as the source ethernet address in all the ethernet frames.

Includes xilsock.h

mac.h

Parameters frame: Buffer for receiving an ethernet frame

len: Buffer size

Returns Number of bytes received

Description Receives an ethernet frame from the MAC, strips the ethernet header and calls either ip or arp callback function based on frame type. This function is called from accept /receive socket functions. The function receives a frame of maximum length len in buffer frame.

Includes xilsock.h

mac.h

Parameters frame: Buffer for sending a ethernet frame

len: Buffer size

dipaddr: Pointer to the destination ip address

dhaddr: Pointer to the destination ethernet address

type: Ethernet Frame type (IP or ARP)

Returns None

Description Creates an ethernet header for payload frame of length len, with destination ethernet address dhaddr, and frame type, type. Sends the ethernet frame to the MAC. This function is called from receive/send (both versions) socket functions.

Includes xilsock.h

mac.h

Page 93: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 93UG114 (v3.0) June 22, 2004 1-800-255-7778

Functions of LibXilNetR

void xilnet_eth_update_hw_tbl (unsigned char* frame, int proto)

void xilnet_eth_add_hw_tbl_entry (unsigned char* ip, unsigned char* hw)

int xilnet_eth_get_hw_addr (unsigned char* ip)

Parameters frame: Buffer containing an ethernet frame

proto: Ethernet Frame type (IP or ARP)

Returns None

Description Updates the hardware address table with ipaddress/hardware address pair from the ethernet frame pointed to by frame. proto is used in identifying the frame (ip/arp) to get the ip address from the ip/arp packet.,

Includes xilsock.h

mac.h

Parameters ip: Buffer contains ip address

hw: Buffer containing hardware address

Returns None

Description Add an ip/hardware pair entry given by ip/hw into the hardware address table

Includes xilsock.h

mac.h

Parameters ip: Buffer containing ip address

Returns Index of entry in the hardware address table that matches the ip address

Description Receives an ethernet frame from the MAC, strips the ethernet header and calls either ip or arp callback function based on the frame type. This function is called from accept /receive socket functions. The function receives a frame of maximum length len in buffer frame.

Includes xilsock.h

mac.h

Page 94: Edk Libs Ref Guide

94 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 6: LibXil NetR

void xilnet_eth_init_hw_addr_tbl (void)

int xilnet_arp (unsigned char* buf, int len)

void xilnet_arp_reply (unsigned char* buf, int len)

void xilnet_ip_init (unsigned char* ip_addr)

Parameters None

Returns None

Description Initializes Hardware Address Table. This function must be called in the user program before using other functions of LibXilNet.

Includes xilsock.h

mac.h

Parameters buf: Buffer for holding the ARP packet

len: Buffer size

Returns 0

Description This is the arp callback function. It gets called by the ethernet driver for arp frame type. The arp packet is copied onto the buf of length len.

Includes xilsock.h

Parameters buf: Buffer containing the ARP reply packet

len: Buffer size

Returns None

Description This function sends the arp reply, present in buf of length len, for arp requests. It gets called from the arp callback function for arp requests.

Includes xilsock.h

Parameters ip_addr: Array of four bytes holding the ip address to be configured

Returns None

Description This function initializes the ip address for the processor to the address represented in ip_addr as a dotted decimal string. This function must be called in the application before any communication.

Includes xilsock.h

Page 95: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 95UG114 (v3.0) June 22, 2004 1-800-255-7778

Functions of LibXilNetR

int xilnet_ip (unsigned char* buf, int len)

void xilnet_ip_header (unsigned char* buf, int len, int proto)

unsigned short xilnet_ip_calc_chksum (unsigned char* buf, int len, int proto)

Parameters buf: Buffer for holding the IP packet

len: Buffer size

Returns 0

Description This is the ip callback function. It gets called by the ethernet driver for ip frame type. The ip packet is copied onto the buf of length len. This function calls in the appropriate protocol callback function based on the protocol type.

Includes xilsock.h

Parameters buf: Buffer for the ip packet

len: Length of the ip packet

proto: Protocol Type in IP packet

Returns None

Description This function fills in the ip header from the start of buf. The ip packet is of length len and proto is used to fill in the protocol field of ip header. This function is called from the receive/send (both versions) functions.

Includes xilsock.h

Parameters buf: Buffer containing ip packet

len: Length of the ip packet

Returns checksum calculated for the given ip packet

Description This function calculates the checksum for the ip packet buf of length len. This function is called from the ip header creation function.

Includes xilsock.h

Page 96: Edk Libs Ref Guide

96 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 6: LibXil NetR

int xilnet_udp (unsigned char* buf, int len)

void xilnet_udp_header (struct xilnet_udp_conn conn, unsigned char* buf, int len)

unsigned short xilnet_udp_tcp_calc_chksum (unsigned char* buf, int len, unsigned char* saddr, unsigned char* daddr, unsigned short proto)

Parameters buf: Buffer containing the UDP packet

len: Length of the UDP packet

Returns Length of the data if packet is destined for any open UDP connections else returns 0

Description This is the udp callback function which is called when ip receives a udp packet. This function checks for a valid udp port, strips the udp header, and demultiplexes from the various UDP connections to select the right connection.

Includes xilsock.h

Parameters conn: UDP connection

buf: Buffer containing udp packet

len: Length of udp packet

Description This function fills in the udp header from the start of buf for the UDP connection conn. The udp packet is of length len. This function is called from the receivefrom/sendto socket functions.

Includes xilsock.h

Parameters buf: Buffer containing UDP/TCP packet

len: Length of udp/tcp packet

saddr: IP address of the source

daddr: Destination IP address

proto: Protocol Type (UDP or TCP)

Returns the

Returns Checksum calculated for the given udp/tcp packet

Description This function calculates and fills the checksum for the udp/tcp packet buf of length len. The source ip address (saddr), destination ip address(daddr) and protocol (proto) are used in the checksum calculation for creating the pseudo header. This function is called from either the udp header or the tcp header creation function.

Includes xilsock.h

Page 97: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 97UG114 (v3.0) June 22, 2004 1-800-255-7778

Functions of LibXilNetR

void xilnet_udp_init_conns (void )

int xilnet_udp_open_conn (unsigned short port)

int xilnet_udp_close_conn (struct xilnet_udp_conn *conn)

int xilnet_tcp (unsigned char* buf, int len)

Parameters None

Returns None

Description Initialize all UDP connections so that the states of all the connections specify that they are usable.

Includes xilsock.h

Parameters port: UDP port number

Returns Connection index if able to open a connection. If not returns -1.

Description Open a UDP connection with port number port.

Includes xilsock.h

Parameters conn: UDP connection

Returns 1 if able to close else returns -1.

Description Close a UDP connection conn.

Includes xilsock.h

Parameters buf: Buffer containing the TCP packet

len: Length of the TCP packet

Returns A status flag based on the state of the connection for which the packet has been received

Description This is the tcp callback function which is called when ip receives a tcp packet. This function checks for a valid tcp port and strips the tcp header. It maintains a finite state machine for all TCP connections. It demultiplexes from existing TCP open/listening connections and performs an action corresponding to the state of the connection. It returns a status flag which identifies the type of TCP packet received (data or ack or fin).

Includes xilsock.h

Page 98: Edk Libs Ref Guide

98 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 6: LibXil NetR

void xilnet_tcp_header (struct xilnet_tcp_conn conn, unsigned char* buf, int len)

void xilnet_tcp_send_pkt (struct xilnet_tcp_conn conn, unsigned char* buf, int len, unsigned char flags)

void xilnet_tcp_init_conns (void )

int xilnet_tcp_open_conn (unsigned short port)

Parameters conn: TCP connection

buf: Buffer containing tcp packet

len: Length of tcp packet

Returns None

Description This function fills in the tcp header from the start of buf for the TCP connection conn. The tcp packet is of length len. It sets the flags in the tcp header.

Includes xilsock.h

Parameters conn: TCP connection

buf: Buffer containing TCP packet

len: Length of tcp packet

Returns The checksum calculated for the given udp/tcp packet

Description This function sends a tcp packet, given by buf of length len, with flags (ack/rst/fin/urg/psh) from connection conn.

Includes xilsock.h

Parameters None

Returns None

Description Initialize all TCP connections so that the states of all the connections specify that they are usable.

Includes xilsock.h

Parameters port: TCP port number

Returns Connection index if able to open a connection. If not returns -1.

Description Open a TCP connection with port number port.

Includes xilsock.h

Page 99: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 99UG114 (v3.0) June 22, 2004 1-800-255-7778

LibGen CustomizationR

int xilnet_tcp_close_conn (struct xilnet_tcp_conn *conn)

int xilnet_icmp (unsigned char* buf, int len)

void xilnet_icmp_echo_reply (unsigned char* buf, int len)

LibGen CustomizationXilNet library is customized through LibGen tool. Here is a snippet from system.mss file for specifying LibXilNet.

BEGIN LIBRARYPARAMETER LIBRARY_NAME = xilnetPARAMETER LIBRARY_VER = 1.00.aPARAMETER device_type = ethernetPARAMETER emac_type = emacEND

LibXilNet has the infrastructure to support different networking devices. The parameter device_type can take - ethernet, serial, host as values. Currently however ethernet is the device type that has been tested.

With ethernet device type, LibXilNet can be used with either the regular ethernet core or the lite version, ethernetlite.

Parameters conn: TCP connection

Returns 1 if able to close else returns -1.

Description Close a TCP connection conn.

Includes xilsock.h

Parameters buf: Buffer containing ICMP packet

len: Length of the ICMP packet

Returns 0

Description This is the icmp callback function which is called when ip receives a icmp echo request packet (ping request). This function checks only for a echo request and sends in an icmp echo reply.

Includes xilsock.h

Parameters buf: Buffer containing ICMP echo reply packet

len: Length of the ICMP echo reply packet

Returns None

Description This functions fills in the icmp header from the start of buf. The icmp packet is of length len. It sends the icmp echo reply by calling the ip, ethernet send functions. This function is called from the icmp callback function.

Includes xilsock.h

Page 100: Edk Libs Ref Guide

100 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 6: LibXil NetR

The parameter emac_type can take - emac, emaclite as values. This configures XilNet to be used with either Emac of EmacLite driver.

Using XilNet in ApplicationLibgen generates a configuration file xilnet_config.h based on the parameter selection in MSS file.

In order to use the XilNet functions in your application, you need to do the following:

� Define “#include <net/xilnet_config.h>” in your C-file.

� Define “#include <net/xilsock.h>” in your C-file.

Table 6-2: Configurable Parameters for XilNet in MSS

Parameter Description

device_type Networking Device type used in the system Possible values are ethernet, serial, host.

emac_type Type of ethernet core used. Possible values are emac, emaclite

Page 101: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 101UG114 (v3.0) June 22, 2004 1-800-255-7778

R

Chapter 7

LibXil File

Xilinx libraries provide block access to file systems and devices using standard calls such as open, close, read, and write. These routines form the LibXil File module of the libraries.

A system can be configured to use the LibXil File module, using the Library Generator (libgen).

This chapter contains the following sections.

� “Overview”

� “Module Usage”

� “Module Routines”

� “Libgen Support”

� “Limitations”

OverviewThe LibXil library provides block access to files and devices through the LibXil File module. This module provides standard routines such as open, close, read, and write to access file systems and devices.

The module LibXil File can also be easily modified to incorporate additional file systems and devices. This module implements a subset of operating system level functions.

Module UsageA file or a device is opened for read and write using the open call in the library. The library maintains a list of open files and devices. Read and write commands can be issued to access blocks of data from the open files and devices.

Module Routines

Functions

int open (const char *name, int flags, int mode)

int close (int fd)

int read (int fd, char* buf, int nbytes)

int write (int fd, char* buf, int nbytes)

Page 102: Edk Libs Ref Guide

102 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 7: LibXil FileR

int open (const char *name, int flags, int mode)

int close (int fd)

int read (int fd, char* buf, int nbytes)

long lseek (int fd, long offset, int whence)

int chdir (const char *buf)

const char* getcwd (void)

Parameters name refers to the name of the device/file.

flags refers to the permissions of the file. This field does not have any meaning for a device.

mode indicates whether the stream is opened in read, write or append mode.

Returns file/device descriptor fd assigned by LibXil File

Description This call registers the device or the file in the local device table and calls the underlying open function for that particular file or a device.

Includes xilfile.h

xparameters.h

Functions

Parameters fd refers to the file descriptor assigned during by open()

Returns If a file is being closed, returns the status returned by the underlying file system. For devices, it returns 1, since devices can not be closed.

0 indicates success in closing a file.

Any other value indicates error

Description Close the file/device with the fd.

Includes xilfile.h

xparameters.h

Parameters fd refers to the file descriptor assigned by open()

buf refers to the destination buffer where the contents of the stream should be copied

nbytes: Number of bytes to be copied

Returns The number of bytes read.

Description Read nbytes from the file/device pointed by the file descriptor fd and store it in the destination pointed by buf.

Includes xilfile.h

xparameters.h

Page 103: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 103UG114 (v3.0) June 22, 2004 1-800-255-7778

Module RoutinesR

int write (int fd, char* buf, int nbytes)

long lseek (int fd, long offset, int whence)

int chdir (char* newdir)

const char* getcwd (void)

Parameters fd: refers to the file descriptor assigned by open()

buf: refers to the source buffer

nbytes: Number of bytes to be copied

Returns The number of bytes written to the file.

Description Write nbytes from the buffer, buf to the file pointed by the file descriptor fd

Includes xilfile.h

xparameters.h

Parameters fd: file descriptor returned by open

offset: Number of bytes to seek

whence: Location to seek from. This parameter depends on the underlying File System being used.

Returns New file pointer location

Description The lseek() system call moves the file pointer for fd by offset bytes from whence.

Includes xilfile.h

xparameters.h

Parameters newdir: Destination directory

Returns The same value as returned by the underlying file system. -1 for failure.

Description Change the current directory to newdir

Includes xilfile.h

xparameters.h

Parameters None

Returns The current working directory.

Description Get the absolute path for the current working directory.

Includes xilfile.h

xparameters.h

Page 104: Edk Libs Ref Guide

104 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 7: LibXil FileR

Libgen Support

LibXil File InstantiationThe users can write application to either interact directly with the underlying file systems and devices or make use of the LibXil File module to integrate with file systems and devices.

In order to instantiate LibXil File module in your system, use the following code in your MSS file.

BEGIN LIBRARY PARAMETER LIBRARY_NAME = xilfile PARAMETER LIBRARY_VER = 1.00.a PARAMETER peripherals = ( ("<peripheral 1 instance name>", "<mount 1>") , ("<peripheral 2 instance name>", "<mount 2>") ) PARAMETER filesys = (( "<Filesystem 1 name>" , "<mount 1>" ), ( "<Filesystem 2 name>" , "<mount 2>" ))END

where

� <peripheral 1 name> : Instance name of the peripheral you need to access through XilFile.

� <mount 1> : Mount name for the <peripheral 1> or <filesystem 1>

� <filesystem 1 name> : Name of the filesystem, you need to access through XilFile. (1)

For example, to access two uarts ( myuart1 and myuart2) and the memory file system ( xilmfs ) , use the following code snippet.

BEGIN LIBRARY PARAMETER LIBRARY_NAME = xilfile PARAMETER LIBRARY_VER = 1.00.a PARAMETER peripherals = ( ("myuart", "/dev/myuart") , ("myuart2", "/dev/myuart2") ) PARAMETER filesys = (( "xilmfs" , "/dev/mfs" ))END

System InitializationLibGen also generates the system initialization file, which is compiled into the LibXil library. This file initialized the data structure required by the LibXil File module, such as the Device tables and the File System table. This routine also initializes STDIN, STDOUT and STDERR, if present.

LimitationsLibXil File module currently enforces the following restrictions:

1. Note that there is no instance name for filesystem and other Xilinx Microkernel modules. Hence, the name of the filesystem should be used instead of the instance name.

Page 105: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 105UG114 (v3.0) June 22, 2004 1-800-255-7778

LimitationsR

� Only one instance of a File System can be mounted. This file system and the mount point has to be indicated in the Microprocessor Software Specification (MSS) file.

� Files cannot have names starting with /dev, since it is a reserved word to be used only for accessing devices.

� Currently LibXil File has support only for 1 file system (LibXil Memory File System) and 3 devices (UART, UARTlite and GPIO).

� Only devices can be assigned as STDIN, STDOUT and STDERR.

Page 106: Edk Libs Ref Guide

106 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 7: LibXil FileR

Page 107: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 107UG114 (v3.0) June 22, 2004 1-800-255-7778

R

Chapter 8

LibXil FATFile System (FATfs)

This chapter describes the XilFatfs FATfile system access library. This library provides read/write access to files stored on a Xilinx SystemAce compact flash or microdrive device.

The chapter contains the following sections.

� “Overview”

� “XilFatfs Functions”

� “LibGen Customization”

OverviewThe XilFatfs filesystem access library provides read/write access to files stored on a Xilinx SystemACE CompactFlash or IBM microdrive device. This library requires the underlying hardware platform to contain all of the following:

� OPB SYSACE Interface Controller - Logicore module

� SystemACE controller and CompactFlash connector

� 128MB or 256MB CompactFlash card formatted with a FAT16, FAT12 or FAT32 file system or an IBM microdrive formatted with a FAT16, FAT12 or FAT32 file system

Caution! FAT16 is required for SystemACE to directly configure the FPGA but the XilFatfs library can work with the SystemACE hardware to support FAT12 and FAT32 as well.

See the documentation on OPB SYSACE Interface Controller in the Processor IP Reference Guide for more details on the hardware.

If this library is to be used in a MicroBlaze system, and speed is of concern, it is recommended that the MicroBlaze processor be configured to include a hardware barrel shifter. See the MicroBlaze documentation for more information on including the barrel shifter.

Users can easily copy files to the flash device from their PC by plugging the flash or microdrive into a suitable USB adapter or similar device.

XilFatfs FunctionsThis section presents a list of functions provided by the XilFatfs. Table 8-1 provides the function names with signature at a glance.

Page 108: Edk Libs Ref Guide

108 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 8: LibXil FATFile System (FATfs)R

Detailed Description of XilFatfsFunctionsvoid *sysace_fopen (const char *file, const char *mode)

Table 8-1: XilFatfs Functions at a Glance

Functions

void *sysace_fopen (const char *file, const char *mode)

int sysace_fread (void *buffer, int size, int count, void *stream)

int sysace_fwrite (void *buffer, int size, int count, void *stream)

int sysace_fclose (void *stream)

void *sysace_mkdir (const char *path)

void *sysace_chdir (const char *path)

Parameters file is the name of the file on the flash device. address is the starting(base) address of the file system memory

mode is restricted to “r” in this version

Returns A non zero file handle on success

0 for failure

Description The file name should follow the Microsoft 8.3 naming standard with a file name of up to 8 characters, followed by a ‘.’ and a 3 character extension. In this version of the library, the 3 character extension is mandatory so a sample file might be called test.txt

This function returns a file handle that has to be used for subsequent calls to read or close the file

If the named file does not exist on the device 0 is returned

Includes sysace_stdio.h

Page 109: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 109UG114 (v3.0) June 22, 2004 1-800-255-7778

XilFatfs FunctionsR

int sysace_fread (void *buffer, int size, int count, void *stream)

int sysace_fwrite (void *buffer, int size, int count, void *stream)

int sysace_fclose (void *stream)

Parameters buffer is a pre allocated buffer that is passed in to this procedure, and is used to return the characters read from the device

size is restricted to 1

count is the number of characters to be read

stream is the file handle returned by sysace_fopen

Returns Non zero number of characters actually read, for success

0 for failure

Description The preallocated buffer is filled with the characters that are read from the device. The return value indicates the actual number of characters read, while count specifies the maximum number of characters to read. The buffer size must be at least count. stream should be a valid file handle returned by a call to sysace_fopen.

Includes sysace_stdio.h

Parameters buffer is a pre allocated buffer that is passed in to this procedure, and contains the characters to be written to the device

size is restricted to 1

count is the number of characters to be written

stream is the file handle returned by sysace_fopen

Returns Non zero number of characters actually written, for success

0 or -1 for failure

Description The preallocated buffer is filled (by the caller) with the characters that are to be written to the device. The return value indicates the actual number of characters written, while count specifies the maximum number of characters to write. The buffer size must be at least count. stream should be a valid file handle returned by a call to sysace_fopen.

Includes sysace_stdio.h

Parameters stream: File handle returned by sysace_fopen

Returns 1 On success

0 On failure

Description Closes an open file

Includes sysace_stdio.h

Page 110: Edk Libs Ref Guide

110 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 8: LibXil FATFile System (FATfs)R

int sysace_mkdir (const char *path)

int sysace_chdir (const char *path)

LibGen CustomizationXilFatfs file system can be integrated with a system using the following snippet in the mss file. There are

BEGIN LIBRARYparameter LIBRARY_NAME = xilfatfsparameter LIBRARY_VER = 1.10.a# The following 3 parameters are optional and their default value is ‘n’parameter CONFIG_WRITE = yparameter CONFIG_DIR_SUPPORT = yparameter CONFIG_FAT12 = yEND

The CONFIG_WRITE parameter when set to ‘y’, adds write capabilities to the library.

Parameters path: path name of new directory

Returns 0 On success

-1On failure

Description Create a new directory specified by path. The directory name can be either absolute or relative, and must follow the 8.3 file naming convention.

Examples: a:\\dirname, a:\\dirname.dir, a:\\dir1\\dirnew, dirname, dirname.dir

If a relative path is specified, and the current working directory is not already set, the current working directory defaults to the root directory.

Includes sysace_stdio.h

Parameters path: path name of new directory

Returns 0 On success

-1On failure

Description Create a new directory specified by path. The directory name can be either absolute or relative, and must follow the 8.3 file naming convention.

Examples: a:\\dirname, a:\\dirname.dir, a:\\dir1\\dirnew, dirname, dirname.dir

If a relative path is specified, and the current working directory is not already set, the current working directory defaults to the root directory.

Includes sysace_stdio.h

Page 111: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 111UG114 (v3.0) June 22, 2004 1-800-255-7778

LibGen CustomizationR

The CONFIG_DIR_SUPPORT parameter when set to ‘y’, adds the mkdir and chdir functions to the library.

The CONFIG_FAT12 parameter when set to ‘y’ configures the library to work with FAT12 file systems. Otherwise the library works with both FAT16 and FAT32 file systems.

Page 112: Edk Libs Ref Guide

112 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 8: LibXil FATFile System (FATfs)R

Page 113: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 113UG114 (v3.0) June 22, 2004 1-800-255-7778

R

Chapter 9

LibXil Memory File System (MFS)

This chapter describes the Memory File System (MFS). This file system resides in RAM/ROM/Flash memory and can be accessed through the LibXil File module or directly. The Memory File System is integrated with a system using the Library Generator.

The chapter contains the following sections.

� “Overview”

� “MFS Functions”

� “Utility Functions”

� “Additional Utilities”

� “C-like access”

� “LibGen Customization”

OverviewThe Memory File System (MFS) component, LibXil MFS, provides users the capability to manage program memory in the form of file handles. Users can create directories, and can have files within each directory. The file system can be accessed from the high level C-language through function calls specific to the file system. Alternatively, users can also manage files through the standard C language functions like open provided in XilFile.

MFS Functions

Quick GlanceThis section presents a list of functions provided by the MFS. Table 9-1 provides the function names with signature at a glance.

Table 9-1: MFS Functions at a Glance

Functions

void mfs_init_fs (int numbytes, char *address, int status)

int mfs_change_dir (char *newdir)

int mfs_get_current_dir_name (char *dirname)

int mfs_create_dir (char *newdir)

int mfs_delete_dir (char *newdir)

Page 114: Edk Libs Ref Guide

114 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 9: LibXil Memory File System (MFS)R

int mfs_exists_file (char *filename)

int mfs_delete_file (char *filename)

int mfs_rename_file (char *from_file, char *to_file)

int mfs_get_usage(int *num_blocks_used, int *num_blocks_free)

int mfs_dir_open (char *dirname)

int mfs_dir_close (int fd)

int mfs_dir_read (int fd, char **filename, int *filesize, int *filetype)

int mfs_file_open (char *filename, int mode)

int mfs_file_read (int fd, char *buf, int buflen)

int mfs_file_write (int fd, char *buf, int buflen)

int mfs_file_close(int fd)

long mfs_file_lseek (int fd, long offset, int whence)

int mfs_ls (void)

int mfs_cat (char *filename)

int mfs_copy_stdin_to_file (char *filename)

int mfs_file_copy (char *from_file, char *to_file)

Table 9-1: MFS Functions at a Glance

Functions

Page 115: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 115UG114 (v3.0) June 22, 2004 1-800-255-7778

MFS FunctionsR

Detailed summary of MFS Functionsint mfs_init_fs (int numbytes, char *address, int status)

int mfs_change_dir (char *newdir)

int mfs_create_dir (char *newdir)

Parameters numbytes is the number of bytes of memory available for the file system

address is the starting(base) address of the file system memory

status is one of MFSINIT_NEW, MFSINIT_IMAGE or MFSINIT_ROM_IMAGE

Returns 1 for success

0 for failure

Description Initialize the memory file system. This function must be called before any file system operation. The status/mode parameter determines certain filesystem properties:

MFSINIT_NEW creates a new, empty file system for read/write

MFSINIT_IMAGE initializes a filesystem whose data has been previously loaded into memory at the base address

MFSINIT_ROM_IMAGE initializes a Read-Only filesystem whose data has been previously loaded into memory at the base address

Includes xilmfs.h

Parameters newdir is the chdir destination.

Returns 1 for success

0 for failure

Description If newdir exists, make it the current directory of MFS. Current directory is not modified in case of failure.

Includes xilmfs.h

Parameters newdir: Directory name to be created

Returns On success, return index of new directory in the file system

On failure, return 0

Description Create a new empty directory called newdir inside the current directory.

Includes xilmfs.h

Page 116: Edk Libs Ref Guide

116 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 9: LibXil Memory File System (MFS)R

int mfs_delete_dir (char *dirname)

int mfs_get_current_dir_name (char *dirname)

int mfs_delete_file (char *filename)

int mfs_rename_file (char *from_file, char *to_file)

Parameters dirname: Directory to be deleted

Returns On success, return index of new directory in the file system

On failure, return 0

Description Delete the directory dirname, if it exists and is empty,

Includes xilmfs.h

Parameters dirname: Current directory name is returned in this pointer

Returns On Success return 0

On failure return 1

Description Return the name of the current directory in a pre allocated buffer, dirname, of at least 16 chars.Note that it does not return the absolute path name of the current directory, but just the name of the current directory

Includes xilmfs.h

Parameters filename: file to be deleted

Returns 1 for success

0 for failure

Description Delete filename from its directory.

Includes xilmfs.h

Parameters from_file: Original filename

to_file: New file name

Returns On success, return 1

On failure, return 0

Description Rename from_file to to_file. Rename works for directories as well as files. Function fails if to_file already exists.

Includes xilmfs.h

Page 117: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 117UG114 (v3.0) June 22, 2004 1-800-255-7778

MFS FunctionsR

int mfs_exists_file (char *filename)

int mfs_get_usage (int *num_blocks_used, int *num_blocks_free)

int mfs_dir_open (char *dirname)

int mfs_dir_close (int fd)

Parameters filename: file/directory to be checked for existence

Returns 0: if filename does not exist

1: if filename is a file

2: if filename is a directory

Description Check if the file/directory is present in current directory.

Includes xilmfs.h

Parameters num_blocks_used: Number of blocks used

num_blocks_free: Number of free blocks

Returns On Success return 0

On failure return 1

Description Get the number of used blocks and the number of free blocks in the file system through pointers.

Includes xilmfs.h

Parameters dirname: directory to be opened for reading

Returns The index of dirname in the array of open files or -1 on failure.

Description Open directory dirname for reading. Reading a directory is done using mfs_dir_read()

Includes xilmfs.h

Parameters fd: File descriptor return by open

Returns On success return 1

On failure return 1

Description Close the dir pointed by fd. The file system regains the fd and uses it for new files.

Includes xilmfs.h

Page 118: Edk Libs Ref Guide

118 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 9: LibXil Memory File System (MFS)R

int mfs_dir_read (int fd, char **filename, int *filesize, int *filetype)

int mfs_file_open (char *filename, int mode)

int mfs_file_read (int fd, char *buf, int buflen)

Parameters fd: File descriptor return by open; passed to this function by caller

filename: Pointer to file name at the current position in the directory in MFS; this value is filled in by this function

filesize: Pointer to a value filled in by this function: Size in bytes of filename, if it is a regular file; Number of directory entries if filename is a directory

filetype: Pointer to a value filled in by this function: MFS_BLOCK_TYPE_FILE if filename is a regular file; MFS_BLOCK_TYPE_DIR if filename is a directory

Returns On Success return number of bytes read.

On Failure return 1

Description Read the current directory entry and advance the internal pointer to the next directory entry. filename, filetype and filesize are pointers to values stored in the current directory entry

Includes xilmfs.h

Parameters filename: file to be opened

mode: Read/Write or Create mode.

Returns The index of filename in the array of open files or -1 on failure.

Description Open file filename with given mode.

The function should be used for files and not directories: MODE_READ, no error checking is done (if file or directory). MODE_CREATE creates a file and not a directory. MODE_WRITE fails if the specified file is a DIR.

Includes xilmfs.h

Parameters fd: File descriptor return by open

buf: Destination buffer for the read

buflen: Length of the buffer

Returns On Success return number of bytes read.

On Failure return 1

Description Read buflen number bytes and place it in buf. fd should be a valid index in “open files” array, pointing to a file, not a directory. buf should be a pre-allocated buffer of size buflen or more. If fewer than buflen chars are available then only that many chars are read.

Includes xilmfs.h

Page 119: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 119UG114 (v3.0) June 22, 2004 1-800-255-7778

MFS FunctionsR

int mfs_file_write (int fd, char *buf, int buflen)

int mfs_file_close (int fd)

long mfs_file_lseek (int fd, long offset, int whence)

Parameters fd: File descriptor return by open

buf: Source buffer from where data is read

buflen: Length of the buffer

Returns On Success return 1

On Failure return 1

Description Write buflen number of bytes from buf to the file. fd should be a valid index in open_files array. buf should be a pre-allocated buffer of size buflen or more.

Includes xilmfs.h

Parameters fd: File descriptor return by open

Returns On success return 1

On failure return 1

Description Close the file pointed by fd. The file system regains the fd and uses it for new files.

Includes xilmfs.h

Parameters fd: File descriptor return by open

offset: Number of bytes to seek

whence: File system dependent mode:

If whence is MFS_SEEK_END, the offset can be either 0 or negative, otherwise offset should be non-negative.

If whence is MFS_SEEK_CURR, the offset is calculated from the current location

If whence is MFS_SEEK_SET, the offset is calculated from the start of the file

Returns On success, return offset from the beginning of the file to the current location

On failure, return -1; the current location is not modified

Description Seek to a given offset within the file at location fd in open_files array.

It is an error to seek before beginning of file or after the end of file.

Includes xilmfs.h

Page 120: Edk Libs Ref Guide

120 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 9: LibXil Memory File System (MFS)R

Utility FunctionsThe following few functions are utility functions that can be used along with Xilinx MFS. These functions are defined in mfs_filesys_util.c and are not declared in xilmfs.h. They must be declared by the user if needed.

int mfs_ls (void)

int mfs_cat (char *filename)

int mfs_copy_stdin_to_file (char *filename)

int mfs_file_copy (char *from_file, char *to_file)

Parameters None

Returns On success return 1

On failure return 0

Description List contents of current directory on STDOUT.

Includes xilmfs.h

Parameters filename: File to be displayed

Returns On success return 1

On failure return 0

Description Print the file to STDOUT.

Includes xilmfs.h

Parameters filename: Destination file.

Returns On success return 1

On failure return 0

Description Copy from STDIN to named file.

Includes xilmfs.h

Parameters from_file: Source file

to_file: Destination file

Returns On success return 1

On failure return 0

Description Copy from_file to to_file. It fails if to_file already exists, or if either could not be opened.

Includes xilmfs.h

Page 121: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 121UG114 (v3.0) June 22, 2004 1-800-255-7778

Additional UtilitiesR

Additional UtilitiesA program called mfsgen is provided along with the MFS library. mfsgen can be used to create an MFS memory image on a host system that can subsequently be downloaded to the embedded system memory. mfsgen itself links to libXilMFS and is compiled to run on the host machine rather than the target MicroBlaze or PowerPC system. Conceptually, this is similar to the familiar zip or tar programs. The source code for mfsgen is provided in the file mfsgen.c in the utils sub-directory. The executable image should be in the path.

An entire directory hierarchy on the host system can be copied to a local MFS file image using mfsgen. This file image can then be downloaded on to the memory of the embedded system for creating a pre-loaded file system. A few test programs are included to show how this is done. More information can be found in the readme.txt file in the utils sub-directory and the “Using XilMFS” chapter in the Platform Studio User Guide.

Usage: mfsgen -txcvsbf [mfs_filename] [num_blocks] <filelist>

Specify exactly one of c,t,x modes

t: list the files in the mfs file system image

c: create an mfs file system image using the list of files specified on the command line

- Directories specified in this list are traversed recursively

x: extract the mfs file system from image to host file system

v: verbose mode

f: specify the host file name (mfs_filename) where the mfs file system image is stored

- If the f option is specified the mfs filename should be specified

- If the f option is omitted the default file name is filesystem.mfs

s: switch endianness

b: number of blocks - should be more than 2

- If the b option is specified the num_blocks value should be specifed

- If the b option is omitted the default value of num_blocks is 5000

- The b option is meaningful only when used in conjunction with the c option

C-like access The user can choose not to deal with the details of the file system by using the standard C-like interface provided by Xil File. It provides the basic C stdio functions like open, close, read, write, and seek. These functions have identical signature as those in the standard ANSI-C. Thus any program with file operations performed using these functions can be easily ported to MFS by interfacing the MFS in conjunction with library Xilfile.

LibGen CustomizationMemory file system can be integrated with a system using the following snippet in the mss file. The memory file system should be instantiated with the name xilmfs. The attributes used by libgen and their descriptions are given in Table 9-2.

BEGIN LIBRARYparameter LIBRARY_NAME = xilmfsparameter LIBRARY_VER = 1.00.a

Page 122: Edk Libs Ref Guide

122 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 9: LibXil Memory File System (MFS)R

parameter numbytes= 50000parameter base_address = 0xffe00000parameter init_type = MFSINIT_NEWparameter need_utils = falseEND

Table 9-2: Attributes for including Memory File System

Attributes Description

numbytes Number of bytes allocated for file system.

base_address Starting address for file system memory

init_type MFSINIT_NEW (default) or MFSINIT_IMAGE or MFSINIT_ROM_IMAGE

MFSINIT_NEW creates a new, empty file system

MFSINIT_ROM_IMAGE creates a file system based on a pre-loaded memory image loaded in memory of size numbytes at starting address base_address. This memory is considered read-only and modification of the file system is not allowed.

MFS_INIT_IMAGE is similar to the previous option except that the file system can be modified, and the memory is considered to be readable and writeable.

need_utils true or false (default = false)

If true, this causes stdio.h to be included from mfs_config.h.

The functions described in the “Utility Functions” section require stdin or stdout to be defined, and setting need_utils to true causes stdio.h to be included.

Caution! The underlying software and hardware platforms must support stdin and stdout peripherals for these utility functions to compile and link correctly.

Page 123: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 123UG114 (v3.0) June 22, 2004 1-800-255-7778

R

Chapter 10

LibXil Profile

This chapter describes the profiling library for embedded processors, libXil Profile. The chapter contains the following sections:

� “Overview”

� “Features”

� “Profiling Model”

� “Customizing xilprofile”

� “Building Applications”

� “Generating GPROF Files”

� “XilProfile Code Description”

� “Limitations”

OverviewProfiling a program running on hardware (board), provides insight into program execution and identifies where it spends most time. Profiling on hardware is faster and the interaction of program with memory and other peripherals can be more accurately captured. LibXil Profile is a software intrusive profile library that generates Call Graph and Histogram information of program running on board. Executing the program on hardware generates the profiling information which is stored on the hardware. XMD generates output file from the data, which can be read by GNU gprof tools (mb-gprof) to generate the profiling information.Profiling is supported for the MicroBlaze processor.

FeaturesLibXil Profile library has the following features:

� Provides Histogram (flat profile) and Call Graph information.

� Histogram: Shows how much time the program spent in each function and how many times the function was called.

� Call Graph: Shows for each function, which functions called it, which other functions it called and how many times.

� Profiling parameters are configurable - Sampling Frequency, Histogram Bin Size and Timer to use.

� Memory location and size to store profiling is flexible and configurable based on program requirements.

Page 124: Edk Libs Ref Guide

124 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 10: LibXil ProfileR

Profiling ModelThe libxil profile library, libxilprofile.a is generated and customized for software platform by instantiating the xilprofile library. Running LibGen will create this library. For more details of Profiling flow refer to the “Profiling Embedded Designs” chapter in the Platform Studio User Guide.

When the profile option -pg is specified to the compiler (mb-gcc and powerpc-eabi-gcc), this library is automatically linked with the application to profile. The generated executable file contains code to generate profile information.

When the program is executed on board, the profile information is stored at the memory location specified by the user. XMD is profile library “aware” and generates the gprof compatible output file based on profile data.

Note: The xilprofile library does not have any explicit application API. The library is linked due to profile calls (_mcount) introduced by gcc for profiling. The are some global variables that need to be set in the application for using the library. This is explained in the later sections.

Customizing xilprofileThe xilprofile library can be customized for an application. Following is the list of PARAMETERS for the library.

Building ApplicationsThe memory needed for storing profile information is allocated in the user application. The memory can be either an array allocated in program or any memory in the hardware system. The latter gives the flexibility to specify any available memory in the system without changing the program’s size or custom linker script. This memory is specified to xilprofile library by two pointer variables in the application.

� char *memstart - Points to start of memory location.

� char *memend - Points to end of memory location.

Table 10-1: xilprofile custom PARAMETERS

Name Type Defaults Description

histogram_binsize int 4 For Histogram calculation, the program is divided into equal sized bins. This parameter specifies the bin size in bytes. This depends on function size.

histogram_sample_freq_hz int 100,000 Frequency of sampling for histogram calculation. This determines the accuracy of histogram calculation.

histogram_timer peripheral instance name

none The opb_timer instance name to use for profiling in the system.

callgraph_no_funcptr boolean false If there is no function pointer in the program, xilprofile uses a method which requires less memory. Setting this parameter to TRUE enables this mode of operation.

Page 125: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 125UG114 (v3.0) June 22, 2004 1-800-255-7778

Generating GPROF FilesR

Application Memory RequirementsThe memory needed for profiling is dependent on the program’s text section size, number of function calls, and presence of function calls. The user can calculate the memory required for profiling by using the TCL file calc_profilemem.tcl

Syntax: calc_profilemem.tcl -target <mblaze> -elf <Executable File compiled without -pg option> -bin <Histogram BIN Size>

Usage: xmd calc_profilemem.tcl -target mblaze -elf executable.elf -bin 4

xilprofile library assumes that the amount of memory allocated is correct and sufficient for the application. This is done to conserve valuable memory. XMD uses the same algorithm to perform memory testing during program download.

Generating GPROF FilesXMD helps in the generation of output files that can be read by GNU gprof tools. XMD does the following functions for profiling.

1. Test if the amount of memory is sufficient for profiling. This test is done when the ELF file is downloaded and is compiled with the -pg option.

2. Read the stored profile information from hardware and generate output files. This is done by the following XMD command.

Syntax: profile out [-o <Output gmon filename>

If output gmon file is not specified, file gmon.out is generated.

Sample Profiling Session using XMD:

Xilinx Microprocessor Debug (XMD) Engine Xilinx EDK 6.2 Build EDK_Gm.8 Copyright (c) 1995-2002 Xilinx, Inc. All rights reserved. XMD% mbconnect mdm JTAG chain configuration -------------------------------------------------- Device ID Code IR Length Part Name 1 0124a093 10 XC2VP7 Assuming, Device No: 1 contains the MicroBlaze system Connected to the JTAG MicroBlaze Debug Module (MDM) No of processors = 1

MicroBlaze Configuration : --------------------------Version............................2.00.a No of PC Breakpoints...............4 No of Read Addr/Data Watchpoints...1 No of Write Addr/Data Watchpoints..1 Instruction Cache Support..........off Data Cache Support.................off

Connected to MicroBlaze "mdm" target. id = 0 Starting GDB server for "mdm" target (id = 0) at TCP port no 1234 XMD% dow microblaze_0/code/executable.elf

**************************************************************** ** Profiling Memory Test ** Executable: microblaze_0/code/executable.elf ** Memory Allocated: 4200

Page 126: Edk Libs Ref Guide

126 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 10: LibXil ProfileR

** Profile Type: PROFILE_FUNCPTR ** Histogram BinSize: 4 **************************************************************** Program Text Size........................5232 No. of Func. Calls.......................33 No. of Func. Ptr. Calls..................3 Memory Histogram Tables..................654 Memory Call Graph Tables.................864

Total Profile Memory required............1518[SUCCESS] XMD% bps 0x470 Setting breakpoint at 0x00000470 XMD% con Processor started. Type "stop" to stop processor RUNNING> stop XMD% profile out Processor stopped at PC: 0x0000177c Profile data written to gmon.out XMD%

GNU gprof tool (mb-gprof) tools can be used to read the output file. Refer to the Manual page of gprof for more information on usage.

XilProfile Code DescriptionXilProfile source code is located at $XILINX_EDK/sw/lib/sw_services/xilprofile_v1_00_a directory.

Some of the important functions are:

� _program_init - This function is called before function main of an application. This function does memory and timer initialization. It allocates memory for histogram (inferred from symbols _ftext and _etext) and call graph based on xilprofile parameters. It initializes the timer routine, registers timer handler accordingly based on timer used and connection to processor and starts the timer. The TCL routine of xilprofile library figures the timer type and connection to processor and generates the #defines. Refer to the “Microprocessor Library Definition (MLD)” chapter in the Embedded System Tools Guide.

� mcount - This function is called by _mcount function, which is inserted at every function start by gcc. This function records the caller and callee information (Instruction address), which is used to generate call graph information. Based on whether function pointers are present or not, different information is stored. This is done to decrease memory needed for profiling if there are no function pointers in the application.

� profile_intr_handler - This is the interrupt handler for the profiling timer. The timer is set to sample the executing application for PC values at fixed intervals and increment the Bin count. This is used to generate the histogram information.

To generate profile output, XMD needs to read xilprofile customization parameters value, profile memory location on the hardware, and actual profile data. XMD does this with the help of global variables in the xilprofile code. The following are the variables used.

� memstart, memend - determines the profile memory used.

� binsize - determines the Histogram BIN size used.

� sample_freq_hz - determines the Sampling Frequency used.

� profile_no_funcptr - determines the method used for call graph.

Page 127: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 127UG114 (v3.0) June 22, 2004 1-800-255-7778

LimitationsR

� _gmonparam - Data stored during profiling and information about the data. Refer profile.h file for more details on this structure.

LimitationsThe profiled program (text section) should exist as contiguous memory.

Page 128: Edk Libs Ref Guide

128 www.xilinx.com EDK OS and Libraries Reference Guide1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 10: LibXil ProfileR

Page 129: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 129UG114 (v3.0) June 22, 2004 1-800-255-7778 Embedded Development Kit

R

Chapter 11

lwIP Library

Overview This chapter describes the Embedded Development Kit (EDK) port of the third party network library, Light Weight IP (lwIP), for embedded processors. The chapter details the port of the lwIP library for PowerPC and MicroBlaze processors. It contains the following sections:

� “Overview”

� “PowerPC System”

� “MicroBlaze System”

� “Setting Up lwIP in EDK”

� “Designing an lwIP Application”

� “Example lwIP Application”

lwIP is an open source implementation of the TCP/IP protocol suite. The lwIP library supports two interfaces - raw API, BSD style Sockets API. EDK has been ported to work with the raw API interface of the library. The features of the lwIP library are :

� IP (Internet Protocol) including packet forwarding on multiple interfaces

� ICMP (Internet Control Message Protocl)

� UDP (User Datagram Protocol)

� TCP (Transmission Control Protocol)

� .Raw API interface support for applications

The raw API provided by lwIP is the lowest level interface of the stack. It has two modes of operation : Event and Callback. The EDK port uses the Callback mode. lwIP stack maintains internal timers for TCP round trip calculations, retransmissions and other TCP facilities. For this purpose, the lwIP timer functions must be called periodically. This is achieved by using the 64-bit hardware timer in PowerPC. For MicroBlaze an external timer is required. The system design involved for both MicroBlaze and PowerPC are discussed in the following sections.

PowerPC System Figure 11-1 shows an example hardware design of a PowerPC based system for lwIP. The system requires a 10/100 ethernet core for performing the network transactions. The built-in hardware timer is used to call the lwIP timer functions periodically.

Page 130: Edk Libs Ref Guide

130 www.xilinx.com EDK OS and Libraries Reference GuideEmbedded Development Kit 1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 11: lwIP LibraryR

MicroBlaze System MicroBlaze does not supoprt an in-built timer. An OPB based timer provides the timer functionality. The system uses the OPB based 10/100 regular ethernet core. A diagram of an example MicroBlaze system design is shown in Figure 11-2.

Figure 11-1: PowerPC System Design for lwIP-Based Echo Server

DSPLB

ISPLB

INT

Non-CritINTC

PLB OPB

PLB2OPBBRIDGE

10/100Ethernet

UART16450

GPIO

UG114_11_01_051404

PPC405

32 KBBRAM

SDRAMMEMC

BRAMMEMC

Figure 11-2: MicroBlaze System Design for lwIP-Based Echo Server

DLMB

IOPB

DOPB

ILMBMICROBLAZE DLMB

OPB

SDRAMMEMC

OPBTIMER

UG114_11_02_051404

Interrupt

BRAMMEMC

32KBRAM

BRAMMEMC

10/100Ethernet

MDM

GPIO

UART16550

ILMB

Page 131: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 131UG114 (v3.0) June 22, 2004 1-800-255-7778 Embedded Development Kit

Memory ManagementR

Memory ManagementThere are two types of memory management in lwIP; the heap memory (mem) and the static memory pools (memp). The pbuf management is a hybrid since it both manages its own memory (th pbuf pool) and uses the heap (mem).

The mem is a heap memory manager, such as the C malloc/free manager. A block of memory is requsted with a call to mem_malloc( ) and the memory is freed with a call to mem_free( ). This is used by code that allocates memory of diffrent sizes. An example is when contents of a packet needs to be copied into a buffer - since the size of the packet isn’t known beforehand, the memory is allocated from the heap.

The memp, on the other hand, uses a set of pools of fixed size memory blocks. This is used by the lwIP stack code to allocate predefined memory blocks. An example is for lwIP stack to allocate memory for TCP protocol control blocks.

The pbufs are used to hold packet data. These are to be used by a network device driver who needs to allocate buffers quickly. The memory options are defined in lwipopts.h file.

The memory options in lwipopts.h are as follows:

Setting Up lwIP in EDK lwIP is customized using the libgen tool. lwIP supports multiple 10/100 ethernet network interfaces. The 48-bit MAC addresses associated with each of the interfaces are given alongwith the ethernet instances used in the MHS file. In order to set up lwIP library in XPS, open the software settings dialog. Select lwip 1.00.a library and click on the Library/OS Parameters tab. Enter the 10/100 ethernet instance names from the MHS file that would be used with the lwIP library. For each of the ethernet instance, a 48-bit MAC address is also specified. The following is an MSS snippet for lwIP library :

BEGIN LIBRARYPARAMETER LIBRARY_NAME = lwipPARAMETER LIBRARY_VER = 1.00.aPARAMETER EMAC_INSTANCES =((my_opb_ethernet,0x00,0x00,0x00,0x00,0x22,0x38))

Table 11-1: Memory Option Settings for lwIP

Option Name Description

MEM_SIZE The size of the heap. If the application will send a lot of data that needs to be copied, this should be set high.

MEMP_NUM_PBUF The number of memp struct pbufs. If the application sends a lot of data out of ROM (or other static memory), this should be set high.

MEMP_NUM_UDP_PCB The number of UDP protocol control blocks. One per active UDP "connection."

MEMP_NUM_TCP_PCB The number of simulatenously active TCP connections.

MEMP_NUM_TCP_PCB_LISTEN The number of listening TCP connections.

MEMP_NUM_TCP_SEG The number of simultaneously queued TCP segments.

Page 132: Edk Libs Ref Guide

132 www.xilinx.com EDK OS and Libraries Reference GuideEmbedded Development Kit 1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 11: lwIP LibraryR

END

Running libgen tool in XPS generates liblwip4.a library in <processor_instance_name>/lib directory in the project area. Applications designed with lwIP should link with this library to get the lwIP functionality. To link a library, open the Compiler options for the application and in the Linker Options, set lwip4 as a library to be used for linking.

libgen Customization lwIP library is customized through libgen tool. Here is a snippet from system.mss file for specifying lwIP library.

BEGIN LIBRARYPARAMETER LIBRARY_NAME = lwipPARAMETER LIBRARY_VER = 1.00.aPARAMETER EMAC_INSTANCES =((my_opb_ethernet,0x00,0x0A,0x35,0x00,0x22,0x20))END

lwIP has the infrastructure to support multiple ethernet interfaces. The parameter emac_instances is an array. It takes in the instance name of an ethernet core (specified in the MHS file) and the 48-bit MAC address corresponding to it. This configures lwIP to use a particular ethernet instance with the 48-bit MAC address.

Designing an lwIP Application Software applications using lwIP should follow certain structure. As mentioned in the previous sections, the lwIP stack requires its timer functon to be called periodically. For PowerPC, the in-build timer is used to calculate the time period. In case of MicroBlaze an external timer is used for providing fixed time periods. For more information on lwIP refer : http://savannah.nongu.org/projects/lwip.

Table 11-2: Configurable Parameters for lwIP in MSS

Parameter Name Description

emac_instances This is an array with parameters emac_instname and the ethernet addresses.This is a list of ethernet instances

that are to be used with lwIP.

emac_instname Name of the ethernet instance from the MHS file

eth_addr0 First byte of the 6-byte MAC address

eth_addr1 Second byte of the 6-byte MAC address

eth_addr2 Third byte of the 6-byte MAC address

eth_addr3 Fourth byte of the 6-byte MAC address

eth_addr4 Fifth byte of the 6-byte MAC address

eth_addr5 Sixth byte of the 6-byte MAC address

Page 133: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 133UG114 (v3.0) June 22, 2004 1-800-255-7778 Embedded Development Kit

Designing an lwIP ApplicationR

Initializing lwIP lwIP requires the application to call several initialization routines. The following is a code snippet that illustrates the initialization routines required for lwIP.

/***************************************************************

* CalllwIP Initialization Routines*****************************************************************/sys_init();mem_init();memp_init();

pbuf_init();netif_init();

tcp_init();/***************************************************************

* Setup our 1 network interface (netif)*****************************************************************/netif = netif_add(&ip_addr, &net_mask, &gw, &XEmacIF_ConfigTable[0],xemacif_init, ip_input);netif_set_default(netif);

An example application is discussed in later sections to illustrate these requirements

lwIP Raw API The raw API of lwIP is the lowest leve interface to the stack. It is also the most efficient interface because it provides direct access to the stack rather than providing extra buffering and message passing features. The following sections describe the most used interface functions. A more detailed description of the raw API is found in the lwIP source tree ($XILINX_EDK/sw/lib/sw_services/lwip_v1_00_a/src/lwip/doc/rawapi.txt). Asynchronous network events (data received, connection established etc.) are communicated to the application through callback functions. These callbacks are registered during the initialization of the TCP connection using the raw API. Table 6-2 lists the events and associated callback routines.

The following section, “Raw APO Functions for TCP,” lists a subset of TCP related functions. For a complete list of functions for other protocols, see: ($XILINX_EDK/sw/lib/sw_services/lwip_v1_00_a/src/lwip/doc/rawapi.txt)

Table 11-3: TCP Events, Callbacks, and Hot to Register Callback Events

Event Callback Register with lwIP

TCP connection established *accept() tcp_accept()

TCP Data Acknowledged by Remote Host

*sent() tcp_sent()

TCP Data Received *recv() tcp_recv()

Page 134: Edk Libs Ref Guide

134 www.xilinx.com EDK OS and Libraries Reference GuideEmbedded Development Kit 1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 11: lwIP LibraryR

Raw APO Functions for TCP

void* tcp_init ()

This function must be called first to initialize the lwIP stack

void tcp_tmr()

This function must be called every TCP_TMR_INTERVAL milliseconds (defined in file lwipopts.h). There are two lower level timer functions which are called inside tcp_tmr( ). The example application calls these functions directly - they are: tcp_slowtmr( ) and tcp_fasttmr( ).

struct tcp_pcb * tcp_new()

tcp_new creates a new TCP Protocol Control Block (PCB) structure.

void tcp_arg (struct tcp_pcb* pcb, void* arg) tcp_arg

Allows the application to register an argument that will be passed back to the application for all callback functions. This argument, arg, is usually used as a pointer to a structure that holds application state information.

err_t tcp_bind (struct tcp_pcb* pcb, struct ip_addr* ip_addr, u16_t port)

Binds the pcb to an IP address, ip_addr and TCP port number port

struct tcp_pcb* tcp_listen (struct tcp_pcb* pcb)

The tcp_listen function instructs the lwIP stack to put the pcb in listen state. The pcb will start to listen for connections on the IP address and port number specified in tcp_bind. When a new connection is established, lwIP calls the callback application function specified using the tcp_accept function.

void tcp_accept (struct tcp_pcb* pcb, err_t (*accept)(void* arg, struct tcp_pcb* newpcb, err_t err))

The tcp_accept function allows the application to register a callback function, accept. The lwIP stack calls the accept function when a new connection is established on a pcb that is in the listening state.

Page 135: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 135UG114 (v3.0) June 22, 2004 1-800-255-7778 Embedded Development Kit

Example lwIP ApplicationR

err_t tcp_write (struct tcp_pcb* pcb, void* dataptr, u16_t len, u8_t copy)

The tcp_write function will write len bytes of data from dataptr to the transmit queue. The copy argument specifies whether or not the stack should copy the data or reference it using the pointer dataptr.

void tcp_sent (struct tcp_pcb* pcb, err_t (*sent)(void* arg, struct tcp_pcb* tpcb, u16_t len))

The tcp_sent function registers the sent callback function. The lwIP stack calls the sent function when data is acknowledged by the remote host. The len argument indicates the number of bytes acknowledged. Once the bytes are acknowledged, the bytes are removed from the transmit buffer creating more space. This is useful when trying to send large amount of data using lwIP. If the tcp_write function fails because the transmit buffer is full, this callback function allows the application to write additional data once buffer space becomes available.

void tcp_recv (struct tcp_pcb* pcb, err_t (*recv)(void* arg, struct tcp_pcb* tpcb, struct pbuf* p, err_t err))

The tcp_recv function registers the recv callback function. The lwIP stack calls the recv function when new data arrives on the connection. The p argument is NULL when the connection is closed.

Example lwIP ApplicationThe following is a simple TCP based echo server application. The echo server is listening for connections on port 7, and echoes the data sent by the client. The following sections discuss the application run on both PowerPC and MicroBlaze.

PowerPC based Echo Server The hardware system for the example is shown in Figure 11-1. Assign drivers to each of these peripherals. Select lwip library as shown before and configure the library with the ethernet instance name and the 6-byte MAC address. The lwip library, liblwip4.a, gets generated in <PROCESSOR_INSTANCE_NAME>/lib/ directory once libgen is run.

C Program

The application is split among the following C and headerf files.

FileName : echo_main.c

/*

. * XILINX IS PROVIDING THIS DESIGN, CODE, OR INFORMATION "AS IS"

. * SOLELY FOR USE IN DEVELOPING PROGRAMS AND SOLUTIONS FOR

Page 136: Edk Libs Ref Guide

136 www.xilinx.com EDK OS and Libraries Reference GuideEmbedded Development Kit 1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 11: lwIP LibraryR

. * XILINX DEVICES. BY PROVIDING THIS DESIGN, CODE, OR INFORMATION

. * AS ONE POSSIBLE IMPLEMENTATION OF THIS FEATURE, APPLICATION

. * OR STANDARD, XILINX IS MAKING NO REPRESENTATION THAT THIS

. * IMPLEMENTATION IS FREE FROM ANY CLAIMS OF INFRINGEMENT,

. * AND YOU ARE RESPONSIBLE FOR OBTAINING ANY RIGHTS YOU MAY REQUIRE

. * FOR YOUR IMPLEMENTATION. XILINX EXPRESSLY DISCLAIMS ANY

. * WARRANTY WHATSOEVER WITH RESPECT TO THE ADEQUACY OF THE

. * IMPLEMENTATION, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OR

. * REPRESENTATIONS THAT THIS IMPLEMENTATION IS FREE FROM CLAIMS OF

. * INFRINGEMENT, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS

. * FOR A PARTICULAR PURPOSE. *

. * (c) Copyright 2002, 2003 Xilinx, Inc.

. * All rights reserved. * */

/*

. * Copyright (c) 2001, 2002, 2003 Swedish Institute of Computer Science.

. * All rights reserved. *

. * Redistribution and use in source and binary forms, with or without

. * modification, are permitted provided that the following conditions

. * are met: *

. * 1. Redistributions of source code must retain the above copyrightnotice,

. * this list of conditions and the following disclaimer.

. * 2. Redistributions in binary form must reproduce the above copyrightnotice,

. * this list of conditions and the following disclaimer in thedocumentation

. * and/or other materials provided with the distribution.

. * 3. The name of the author may not be used to endorse or promoteproducts

. * derived from this software without specific prior written

permission. *

. * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ‘‘AS IS’’ AND ANY EXPRESS OR

. * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES

Page 137: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 137UG114 (v3.0) June 22, 2004 1-800-255-7778 Embedded Development Kit

Example lwIP ApplicationR

. * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE AREDISCLAIMED. IN

. * NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,INCIDENTAL,

. * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOTLIMITED

. * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,OR

. * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORYOF

. * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING

. * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS

. * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. * */

/* Xilinx Includes */#include "xuartns550_l.h"#include "xtime_l.h"#include "xparameters.h"#include "xcache_l.h"#include "xgpio_l.h"

/* lwIP Includes */#include "netif/xemacif.h"#include "lwip/tcp.h"#include "lwip/memp.h"#include "netif/etharp.h"

#include "echo.h"

#define UART_BASEADDR XPAR_MYUART_16550_BASEADDR#define UART_CLOCK (XPAR_XUARTNS550_CLOCK_HZ)#define UART_BAUDRATE (115200)

#define LWIP_TIMER_CYCLES (XPAR_CPU_PPC405_CORE_CLOCK_FREQ_HZ / 1000 \

* TCP_TMR_INTERVAL )// Upper 6 bytes of MAC - Xilinx Ethernet OUI = 00-0A-35#define XILINX_MAC_OUI0 0x00#define XILINX_MAC_OUI1 0x00#define XILINX_MAC_OUI2 0x00

static void show_dotted_decimal( char * address_array);static void show_dashed_hex( int bytes, char *address_array);

// Static Global Variablesstatic u8_t my_timer = 0;

// External Global Variables

/* defined in lwip/src/core/tcp.c */extern u32_t tcp_ticks;

Page 138: Edk Libs Ref Guide

138 www.xilinx.com EDK OS and Libraries Reference GuideEmbedded Development Kit 1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 11: lwIP LibraryR

/* defined in EDK generated xemacif_g.c file */extern XEmacIf_Config XEmacIf_ConfigTable[];

/*------------------------------------------------------------------*/

* show dotted decimal prints a dotted decimal address to the UART*------------------------------------------------------------------*/static void show_dotted_decimal( char *address_array){

int bb; char temp;

for(bb=0;bb<4;bb++)

{ temp = address_array[bb]; if(bb!=0) xil_printf("."); xil_printf("%d", (int) temp);

}}

/*------------------------------------------------------------------*//* show dashed hex prints a dashed hex address to the UART *//*------------------------------------------------------------------*/static void show_dashed_hex( int bytes, char *address_array){

//Assumes the caller passes the correct number of bytes int bb;

for(bb=0;bb<bytes;bb++)

{ if(bb !=0) xil_printf("-"); xil_printf("%02X", (int) address_array[bb]);

}}

/*------------------------------------------------------------------*//* my_tmr - Called Periodically to dispatch TCP and ARP timers *//*------------------------------------------------------------------*/void my_tmr(void){

++my_timer;

if(my_timer == 10) {

my_timer = 0; } if(my_timer & 1) {

/* Call tcp_fasttmr() every 2 ms, i.e.,

* every other timer my_tmr() is called. */

Page 139: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 139UG114 (v3.0) June 22, 2004 1-800-255-7778 Embedded Development Kit

Example lwIP ApplicationR

tcp_fasttmr(); } if(my_timer == 0 || my_timer == 5) {

/* Call tcp_slowtmr() every 5 ms, i.e.,

* every fifth timer my_tmr() is called. */ tcp_slowtmr(); if (tcp_ticks%2000 == 0)

/* Call etharp_tmr() every 20th call to tcp_slowtmr().

* tcp_ticks is a global var defined in core/tcp.c */etharp_tmr(); }}

/*------------------------------------------------------------------*//* print_app_header - prints the legal header *//*------------------------------------------------------------------*/void print_app_header(){

xil_printf("\n\n\n\n\n\n\n\n\n");

xil_printf("####################################################################\n");

xil_printf("# Xilinx TCP/IP Demo Application (ECHO Server) #\n"); xil_printf("# \n");xil_printf("# XILINX IS PROVIDING THIS DESIGN, CODE, OR INFORMATION

’AS IS’ #\n"); xil_printf("# SOLELY FOR USE IN DEVELOPING PROGRAMS AND SOLUTIONS FOR # \n"); xil_printf("# XILINX DEVICES. # \n"); xil_printf("# # \n"); xil_printf("# (c) Copyright 2003, 2003 Xilinx, Inc. # \n"); xil_printf("# All rights reserved. # \n"); xil_printf("# # \n");

xil_printf("####################################################################\n");}

/*------------------------------------------------------------------*//* main function *//*------------------------------------------------------------------*/int main_main ()

Page 140: Edk Libs Ref Guide

140 www.xilinx.com EDK OS and Libraries Reference GuideEmbedded Development Kit 1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 11: lwIP LibraryR

{

struct tcp_pcb *gddpp_pcb; struct ip_addr ipaddr, netmask, gw; struct netif *default_netif; char menu_select = 0; XTime ml_base, ml_new, ml_offset; int waiting_for_timer = 1; char low_mac[3] = {0x00,0x22,0x38}; char fullmac[6] = {XILINX_MAC_OUI0, XILINX_MAC_OUI1,

XILINX_MAC_OUI2,

low_mac[0], low_mac[2], low_mac[3]}; char ip[4] = {149,199,6,108}; char subnet[4] = {255,255,255,0}; char gateway[4] = {149,199,6,254};

unsigned int init_wait = 15000000;

/*----------------------------------------------------------------

* Uart Init* *----------------------------------------------------------------*/

/* Disable Interrupts */ XIo_Out8(UART_BASEADDR + XUN_LCR_OFFSET, 0UL); XIo_Out8(UART_BASEADDR + XUN_IER_OFFSET, 0UL);

/* Clear Latches */ XIo_In8(UART_BASEADDR + XUN_LSR_OFFSET); XIo_In8(UART_BASEADDR + XUN_IIR_OFFSET); XIo_In8(UART_BASEADDR + XUN_MSR_OFFSET);

/* Disable FIFOs (16450) */ XIo_Out8(UART_BASEADDR + XUN_FCR_OFFSET, 0UL);

/* Normal ABQ level 0 driver inits */ XUartNs550_SetBaud(UART_BASEADDR, UART_CLOCK, UART_BAUDRATE); XUartNs550_mSetLineControlReg(UART_BASEADDR, XUN_LCR_8_DATA_BITS);

/* Sets DTR, RTS, and OUT2 in the MCR */ XIo_Out8(UART_BASEADDR + XUN_MCR_OFFSET, XUN_MCR_OUT_2 | XUN_MCR_RTS | XUN_MCR_DTR);

xil_printf("\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n"); xil_printf("Starting Up...\n"); xil_printf("Console: 16550 initialized.\n");

/*---------------------------------------------------------------*/

/* Timer Inits */ /*---------------------------------------------------------------*/ ml_offset = LWIP_TIMER_CYCLES;

Page 141: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 141UG114 (v3.0) June 22, 2004 1-800-255-7778 Embedded Development Kit

Example lwIP ApplicationR

/*---------------------------------------------------------------*/

/* Do LWIP System Inits */ /*---------------------------------------------------------------*/ #ifdef STATS

stats_init();#endif /* STATS */xil_printf("Initializing Memory Structures.");sys_init();mem_init();xil_printf(".");memp_init();xil_printf(".");

pbuf_init(); xil_printf(" done.\n");

// clear UART Receive Buffer while (XUartNs550_mIsReceiveData(UART_BASEADDR)) { XUartNs550_RecvByte(UART_BASEADDR); }

// set GPIO I/O Mask XGpio_mSetDataDirection(XPAR_MYGPIO_BASEADDR, 0x00000FFF);

// Turn on 4 LEDs (Active Low) XGpio_mSetDataReg(XPAR_MYGPIO_BASEADDR, 0x00000000);

/*---------------------------------------------------------------*/ /* Initial Header and Menus. Do this before the netif_init() so */ /* we can change the MAC Address and IP addresses if needed */ /*---------------------------------------------------------------*/ while(init_wait--); print_app_header(); fullmac[0] = XILINX_MAC_OUI0; fullmac[1] = XILINX_MAC_OUI1; fullmac[2] = XILINX_MAC_OUI2; fullmac[3] = low_mac[0]; fullmac[4] = low_mac[1]; fullmac[5] = low_mac[2];

/*---------------------------------------------------------------*/

/* Set host addresses */ /*---------------------------------------------------------------*/xemacif_setmac(0, (u8_t *) fullmac); //Set MAC IP4_ADDR(&gw, gateway[0],gateway[1],gateway[2],gateway[3]); //Set

gatewayIP4_ADDR(&ipaddr, ip[0],ip[1],ip[2],ip[3]); //Set ip IP4_ADDR(&netmask,subnet[0],subnet[1],subnet[2],subnet[3]); //Set

subnet msk

/*---------------------------------------------------------------*/

/* Show some host boot stuff and parameters */ /*---------------------------------------------------------------*/

Page 142: Edk Libs Ref Guide

142 www.xilinx.com EDK OS and Libraries Reference GuideEmbedded Development Kit 1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 11: lwIP LibraryR

xil_printf("

\nStarting Network Interface...\n");

xil_printf(" MAC Address: "); show_dashed_hex(6, fullmac);xil_printf("\n");

xil_printf(" IP Address: "); show_dotted_decimal(ip);xil_printf("\n");

xil_printf(" Subnet Mask: "); show_dotted_decimal(subnet);xil_printf("\n");

xil_printf(" Gateway IP: "); show_dotted_decimal(gateway);xil_printf("\n");

xil_printf(" Echo Port: 7

\n");

/*---------------------------------------------------------------*/

/* Initialize netif */ /*---------------------------------------------------------------*/ netif_init();

/*---------------------------------------------------------------*/

/* Initialize TCP Stack */ /*---------------------------------------------------------------*/ tcp_init();

/*---------------------------------------------------------------*/

/* Set up the lwIP network interface... */ /*---------------------------------------------------------------*/ default_netif = netif_add(&ipaddr,

&netmask, &gw,

&XEmacIf_ConfigTable[0], xemacif_init, ip_input );

netif_set_default(default_netif);

/*---------------------------------------------------------------*/ /* create new tcp pcb and start applications */ /*---------------------------------------------------------------*/

// Start the Server xil_printf("Echo Server Running ... "); xil_printf("

Page 143: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 143UG114 (v3.0) June 22, 2004 1-800-255-7778 Embedded Development Kit

Example lwIP ApplicationR

\n"); echo_init();

// Get the current Time-Base Register Value // offset it by ml_offset XTime_SetTime(0); XTime_GetTime(&ml_base); ml_base += ml_offset;

while (1) {

while (waiting_for_timer) { xemacif_input(default_netif); XTime_GetTime(&ml_new); if ( ml_new >= ml_base ) {

waiting_for_timer = 0; ml_base = ml_new + ml_offset;

} } // Call my_tmr() every ml_offset cycles my_tmr(); waiting_for_timer = 1;

} return (1);}

int main (){

/*---------------------------------------------------------------*//* Enable instruction and data cache -this must be done first because*/ /* the Memec Design Virtex-II Dev Boards (rev1 and rev2) have the

SDRAM */ /* byte enables tied together on the board. Enabling the caches */ /* guarantees that all memory accesses are 32-bit aligned. */ /*---------------------------------------------------------------*/ XCache_EnableICache(0x80000001); XCache_EnableDCache(0x80000001); return main_main();

}

FileName : echo.c

/*

. * Copyright (c) 2001-2003 Swedish Institute of Computer Science.

. * All rights reserved. *

. * Redistribution and use in source and binary forms, with or withoutmodification,

Page 144: Edk Libs Ref Guide

144 www.xilinx.com EDK OS and Libraries Reference GuideEmbedded Development Kit 1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 11: lwIP LibraryR

. * are permitted provided that the following conditions are met: *

. * 1. Redistributions of source code must retain the above copyrightnotice,

. * this list of conditions and the following disclaimer.

. * 2. Redistributions in binary form must reproduce the above copyrightnotice,

. * this list of conditions and the following disclaimer in thedocumentation

. * and/or other materials provided with the distribution.

. * 3. The name of the author may not be used to endorse or promoteproducts

. * derived from this software without specific prior written

permission. *

. * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ‘‘AS IS’’ AND ANY EXPRESS ORIMPLIED

. * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF

. * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.IN NO EVENT

. * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,SPECIAL,

. * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,PROCUREMENT

. * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; ORBUSINESS

. * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHERIN

. * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OROTHERWISE) ARISING

. * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THEPOSSIBILITY

. * OF SUCH DAMAGE. *

. * This file is part of the lwIP TCP/IP stack. *

. * Author: Adam Dunkels <[email protected]>

* */

Page 145: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 145UG114 (v3.0) June 22, 2004 1-800-255-7778 Embedded Development Kit

Example lwIP ApplicationR

#include "lwip/debug.h"#include "lwip/stats.h"#include "lwip/tcp.h"#include "xparameters.h"#include "echo.h"

struct echo_state { struct pbuf *p; u8_t failed;

#define FAILED_MAX 8};/*------------------------------------------------------------------*/static voidecho_err(void *arg, err_t err){

struct echo_state *es = arg;

xil_printf("echo_err\n");

if(arg != NULL) { pbuf_free(es->p); mem_free(arg);

}}/*------------------------------------------------------------------*/static voidclose_conn(struct tcp_pcb *pcb, struct echo_state *es){

tcp_arg(pcb, NULL); tcp_sent(pcb, NULL); tcp_recv(pcb, NULL); if(es != NULL) {

pbuf_free(es->p);

mem_free(es); } tcp_close(pcb);xil_printf("Connection Closed

\n");}/*------------------------------------------------------------------*/static voidsend_buf(struct tcp_pcb *pcb, struct echo_state *es){

struct pbuf *q;

do { q = es->p; es->p = pbuf_dechain(q); if(tcp_write(pcb, q->payload, q->len, 1) == ERR_MEM) {

Page 146: Edk Libs Ref Guide

146 www.xilinx.com EDK OS and Libraries Reference GuideEmbedded Development Kit 1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 11: lwIP LibraryR

pbuf_chain(q, es->p); es->p = q; return;

} tcp_recved(pcb, q->len); pbuf_free(q);

} while(es->p != NULL);}/*------------------------------------------------------------------*/static err_techo_poll(void *arg, struct tcp_pcb *pcb){

struct echo_state *es;

if(arg == NULL) { return tcp_close(pcb); }

es = arg;

if(es->failed >= FAILED_MAX) { close_conn(pcb, es); tcp_abort(pcb); return ERR_ABRT;

}

if(es->p != NULL) { ++es->failed; send_buf(pcb, es);

}

return ERR_OK;}/*------------------------------------------------------------------*/static err_techo_sent(void *arg, struct tcp_pcb *pcb, u16_t len){

struct echo_state *es;

es = arg;

if(es != NULL && es->p != NULL) {

send_buf(pcb, es); } return ERR_OK;

}/*------------------------------------------------------------------*/static err_techo_recv(void *arg, struct tcp_pcb *pcb, struct pbuf *p, err_t err){

Page 147: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 147UG114 (v3.0) June 22, 2004 1-800-255-7778 Embedded Development Kit

Example lwIP ApplicationR

struct echo_state *es;

es = arg;

if(p == NULL) { close_conn(pcb, es); return ERR_OK;

}

if(es->p != NULL) { pbuf_chain(es->p, p); } else { es->p = p;

}

send_buf(pcb, es);

return ERR_OK;}/*------------------------------------------------------------------*/static err_techo_accept(void *arg, struct tcp_pcb *pcb, err_t err){

struct echo_state *es;

tcp_setprio(pcb, TCP_PRIO_MIN);

/* Allocate memory for the structure that holds the state of the connection. */ es = mem_malloc(sizeof(struct echo_state));

if(es == NULL) { xil_printf("could not malloc memory for echo_state\n"); return ERR_MEM; }

/* Initialize the structure. */ es->p = NULL; es->failed = 0;

/* Tell TCP that this is the structure we wish to be passed for our callbacks. */ tcp_arg(pcb, es);

/* Tell TCP that we wish to be informed of incoming data by a call

to the http_recv() function. */ tcp_recv(pcb, echo_recv); tcp_err(pcb, echo_err); tcp_poll(pcb, echo_poll, 1);

xil_printf("Connection Established

\n");

Page 148: Edk Libs Ref Guide

148 www.xilinx.com EDK OS and Libraries Reference GuideEmbedded Development Kit 1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 11: lwIP LibraryR

return ERR_OK;}/*------------------------------------------------------------------*/voidecho_init(void){

struct tcp_pcb *pcb;

pcb = tcp_new(); tcp_bind(pcb, IP_ADDR_ANY, ECHO_PORT); pcb = tcp_listen(pcb); tcp_accept(pcb, echo_accept);

}/*------------------------------------------------------------------*/

FileName : echo.h

#ifndef LWIP_ECHO_H#define LWIP_ECHO_H

#define ECHO_PORT 7

void echo_init(void);

#endif

Linker script

The linker script used with the above example. /********************************************************************* *

. * XILINX IS PROVIDING THIS DESIGN, CODE, OR INFORMATION "AS IS"

. * SOLELY FOR USE IN DEVELOPING PROGRAMS AND SOLUTIONS FOR

. * XILINX DEVICES. BY PROVIDING THIS DESIGN, CODE, OR INFORMATION

. * AS ONE POSSIBLE IMPLEMENTATION OF THIS FEATURE, APPLICATION

. * OR STANDARD, XILINX IS MAKING NO REPRESENTATION THAT THIS

. * IMPLEMENTATION IS FREE FROM ANY CLAIMS OF INFRINGEMENT,

. * AND YOU ARE RESPONSIBLE FOR OBTAINING ANY RIGHTS YOU MAY REQUIRE

. * FOR YOUR IMPLEMENTATION. XILINX EXPRESSLY DISCLAIMS ANY

. * WARRANTY WHATSOEVER WITH RESPECT TO THE ADEQUACY OF THE

. * IMPLEMENTATION, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OR

. * REPRESENTATIONS THAT THIS IMPLEMENTATION IS FREE FROM CLAIMS OF

Page 149: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 149UG114 (v3.0) June 22, 2004 1-800-255-7778 Embedded Development Kit

Example lwIP ApplicationR

. * INFRINGEMENT, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS

. * FOR A PARTICULAR PURPOSE. *

. * (c) Copyright 2003 Xilinx, Inc.

. * All rights reserved. *

*********************************************************************/

_STACK_SIZE = 1024k;_HEAP_SIZE = 1024k;

MEMORY

{ sdram : ORIGIN = 0x00000000, LENGTH = 32M bram : ORIGIN = 0xFFFF8000, LENGTH = 32K - 4 boot : ORIGIN = 0xfffffffc, LENGTH = 4

}

STARTUP(boot.o)ENTRY(_boot)GROUP(libxil.a libc.a)

SECTIONS{.vectors : { *(.vectors)

} > sdram

.text : { *(.text) } > sdram

.data :

{ *(.data) *(.got2) *(.rodata) *(.fixup)

} > sdram

/* small data area (read/write): keep together! */ .sdata : { *(.sdata) } > sdram

.sbss :

{ . = ALIGN(4); *(.sbss) . = ALIGN(4);

Page 150: Edk Libs Ref Guide

150 www.xilinx.com EDK OS and Libraries Reference GuideEmbedded Development Kit 1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 11: lwIP LibraryR

} > sdram

__sbss_start = ADDR(.sbss); __sbss_end = ADDR(.sbss) + SIZEOF(.sbss);

/* small data area 2 (read only) */ .sdata2 : { *(.sdata2) } > sdram

.bss :

{ . = ALIGN(4); *(.bss) *(COMMON) . = ALIGN(4);

__bss_end = .;

/* add stack and align to 16 byte boundary */ . = . + _STACK_SIZE; . = ALIGN(16); __stack = .; _heap_start = .; . = . + _HEAP_SIZE; . = ALIGN(16); _heap_end = .;

} > sdram

__bss_start = ADDR(.bss); .boot0 :

{ *(.boot0) _end = .;

} > sdram

.boot : { *(.boot) } > boot

}

MicroBlaze-Based Echo Server The hardware system for the example is shown in Figure 11-2. Assign drivers to each of these peripherals. Select lwip library as shown before and configure the library with the ethernet instance name and the 6-byte MAC address. The lwip library, liblwip4.a, gets generated in <PROCESSOR_INSTANCE_NAME>/lib/ directory once libgen is run.

C Program

The application is split among the following C and headerf files.

FileName : echo_main.c

/*

Page 151: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 151UG114 (v3.0) June 22, 2004 1-800-255-7778 Embedded Development Kit

Example lwIP ApplicationR

. * XILINX IS PROVIDING THIS DESIGN, CODE, OR INFORMATION "AS IS"

. * SOLELY FOR USE IN DEVELOPING PROGRAMS AND SOLUTIONS FOR

. * XILINX DEVICES. BY PROVIDING THIS DESIGN, CODE, OR INFORMATION

. * AS ONE POSSIBLE IMPLEMENTATION OF THIS FEATURE, APPLICATION

. * OR STANDARD, XILINX IS MAKING NO REPRESENTATION THAT THIS

. * IMPLEMENTATION IS FREE FROM ANY CLAIMS OF INFRINGEMENT,

. * AND YOU ARE RESPONSIBLE FOR OBTAINING ANY RIGHTS YOU MAY REQUIRE

. * FOR YOUR IMPLEMENTATION. XILINX EXPRESSLY DISCLAIMS ANY

. * WARRANTY WHATSOEVER WITH RESPECT TO THE ADEQUACY OF THE

. * IMPLEMENTATION, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OR

. * REPRESENTATIONS THAT THIS IMPLEMENTATION IS FREE FROM CLAIMS OF

. * INFRINGEMENT, IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS

. * FOR A PARTICULAR PURPOSE. *

. * (c) Copyright 2002, 2003 Xilinx, Inc.

. * All rights reserved. * */

/*

. * Copyright (c) 2001, 2002, 2003 Swedish Institute of Computer Science.

. * All rights reserved. *

. * Redistribution and use in source and binary forms, with or without

. * modification, are permitted provided that the following conditions

. * are met: *

. * 1. Redistributions of source code must retain the above copyrightnotice,

. * this list of conditions and the following disclaimer.

. * 2. Redistributions in binary form must reproduce the above copyrightnotice,

. * this list of conditions and the following disclaimer in thedocumentation

. * and/or other materials provided with the distribution.

. * 3. The name of the author may not be used to endorse or promoteproducts

. * derived from this software without specific prior written

permission. *

. * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ‘‘AS IS’’ AND ANY EXPRESS OR

. * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES

Page 152: Edk Libs Ref Guide

152 www.xilinx.com EDK OS and Libraries Reference GuideEmbedded Development Kit 1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 11: lwIP LibraryR

. * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE AREDISCLAIMED. IN

. * NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,INCIDENTAL,

. * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOTLIMITED

. * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,OR

. * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORYOF

. * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING

. * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS

. * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. * */

/* Xilinx Includes */#include "xuartns550_l.h"#include "xparameters.h"#include "xgpio_l.h"#include "xtmrctr_l.h"

/* lwIP Includes */#include "netif/xemacif.h"#include "lwip/tcp.h"#include "lwip/memp.h"#include "netif/etharp.h"

#include "echo.h" #define UART_BASEADDR XPAR_MYUART_16550_BASEADDR #define UART_CLOCK (XPAR_XUARTNS550_CLOCK_HZ) #define UART_BAUDRATE (115200)

#define LWIP_TIMER_CYCLES (XPAR_CPU_PPC405_CORE_CLOCK_FREQ_HZ / 1000 \

* TCP_TMR_INTERVAL )// Upper 6 bytes of MAC - Xilinx Ethernet OUI = 00-0A-35#define XILINX_MAC_OUI0 0x00#define XILINX_MAC_OUI1 0x00#define XILINX_MAC_OUI2 0x00

static void show_dotted_decimal( char * address_array);static void show_dashed_hex( int bytes, char *address_array);

// Static Global Variablesstatic u8_t my_timer = 0;static int waiting_for_timer = 1;

/* defined in lwip/src/core/tcp.c */extern u32_t tcp_ticks;

Page 153: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 153UG114 (v3.0) June 22, 2004 1-800-255-7778 Embedded Development Kit

Example lwIP ApplicationR

/* defined in EDK generated xemacif_g.c file */extern XEmacIf_Config XEmacIf_ConfigTable[];

/*------------------------------------------------------------------*/// show dotted decimal prints a dotted decimal address to the UART/*------------------------------------------------------------------*/static void show_dotted_decimal( char *address_array)

{ int bb; unsigned char temp;

for(bb=0;bb<4;bb++)

{ temp = address_array[bb]; if(bb!=0) xil_printf("."); xil_printf("%d", temp);

}}

/*------------------------------------------------------------------*//* show dashed hex prints a dashed hex address to the UART *//*------------------------------------------------------------------*/static void show_dashed_hex( int bytes, char *address_array){

//Assumes the caller passes the correct number of bytes int bb;

for(bb=0;bb<bytes;bb++)

{ if(bb !=0) xil_printf("-"); xil_printf("%02X", (int) address_array[bb]);

}}

/*------------------------------------------------------------------*//* my_tmr - Called Periodically to dispatch TCP and ARP timers *//*------------------------------------------------------------------*/void my_tmr(void){

++my_timer;

if(my_timer == 10) {

my_timer = 0; } if(my_timer & 1) {

/* Call tcp_fasttmr() every 2 ms, i.e.,

* every other timer my_tmr() is called. */tcp_fasttmr(); }

Page 154: Edk Libs Ref Guide

154 www.xilinx.com EDK OS and Libraries Reference GuideEmbedded Development Kit 1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 11: lwIP LibraryR

if(my_timer == 0 || my_timer == 5) {

/* Call tcp_slowtmr() every 5 ms, i.e.,

* every fifth timer my_tmr() is called. */ tcp_slowtmr(); if (tcp_ticks%2000 == 0)

/* Call etharp_tmr() every 20th call to tcp_slowtmr().

* tcp_ticks is a global var defined in core/tcp.c */ etharp_tmr();

}}

/*------------------------------------------------------------------*//* print_app_header - prints the legal header *//*------------------------------------------------------------------*/void print_app_header(){

xil_printf("\n\n\n\n\n\n\n\n

\n");

xil_printf("####################################################################\n");

xil_printf("# Xilinx TCP/IP Demo Application (ECHO Server)#\n");

xil_printf("# #\n");xil_printf("# XILINX IS PROVIDING THIS DESIGN, CODE, OR INFORMATION

’AS IS’ # \n"); xil_printf("# SOLELY FOR USE IN DEVELOPING PROGRAMS AND SOLUTIONS FOR # \n"); xil_printf("# XILINX DEVICES. # \n"); xil_printf("# # \n"); xil_printf("# (c) Copyright 2003, 2003 Xilinx, Inc. # \n"); xil_printf("# All rights reserved. # \n"); xil_printf("# # \n");

xil_printf("####################################################################\n");

Page 155: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 155UG114 (v3.0) June 22, 2004 1-800-255-7778 Embedded Development Kit

Example lwIP ApplicationR

}

/*------------------------------------------------------------------*//* main function *//*------------------------------------------------------------------*/int main_main (){

struct tcp_pcb *gddpp_pcb; struct ip_addr ipaddr, netmask, gw; struct netif *default_netif; char menu_select = 0;

char low_mac[3] = {0x00,0x22,0x38}; char fullmac[6] = {XILINX_MAC_OUI0, XILINX_MAC_OUI1,XILINX_MAC_OUI2,

low_mac[0], low_mac[2], low_mac[3]}; char ip[4] = {149,199,6,108}; char subnet[4] = {255,255,255,0}; char gateway[4] = {149,199,6,254}; int app_running = 0; unsigned int init_wait = 15000000;

/*------------------------------

* Enable microblaze interrupts *-------------------------------*/

microblaze_enable_interrupts();

/*----------------------------------------------------------------

. * Timer and Intc Init *

. * Set the Timer to interrupt for every 100ms *---------------------------------------------------------------*/

/* set the number of cycles the timer counts before interrupting */

/* 100 Mhz clock => 100 us for 1 clk tick. For 100ms, 1000 clk ticksneed to elapse */

XTmrCtr_mSetLoadReg(XPAR_OPB_TIMER_1_BASEADDR, 0, 10000);

/* reset the timers, and clear interrupts */

XTmrCtr_mSetControlStatusReg(XPAR_OPB_TIMER_1_BASEADDR, 0,XTC_CSR_INT_OCCURED_MASK | XTC_CSR_LOAD_MASK );

/* start the timers */

XTmrCtr_mSetControlStatusReg(XPAR_OPB_TIMER_1_BASEADDR, 0,XTC_CSR_ENABLE_TMR_MASK | XTC_CSR_ENABLE_INT_MASK |XTC_CSR_AUTO_RELOAD_MASK | XTC_CSR_DOWN_COUNT_MASK);

/*----------------------------------------------------------------

Page 156: Edk Libs Ref Guide

156 www.xilinx.com EDK OS and Libraries Reference GuideEmbedded Development Kit 1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 11: lwIP LibraryR

* Uart Init*-------------------------------------------------------------------*/

/* Disable Interrupts */

XIo_Out8(UART_BASEADDR + XUN_LCR_OFFSET, 0UL);

XIo_Out8(UART_BASEADDR + XUN_IER_OFFSET, 0UL);

/* Clear Latches */

XIo_In8(UART_BASEADDR + XUN_LSR_OFFSET);

XIo_In8(UART_BASEADDR + XUN_IIR_OFFSET);

XIo_In8(UART_BASEADDR + XUN_MSR_OFFSET);

/* Disable FIFOs (16450) */

XIo_Out8(UART_BASEADDR + XUN_FCR_OFFSET, 0UL);

/* Normal ABQ level 0 driver inits */ XUartNs550_SetBaud(UART_BASEADDR, UART_CLOCK, UART_BAUDRATE); XUartNs550_mSetLineControlReg(UART_BASEADDR, XUN_LCR_8_DATA_BITS);

/* Sets DTR, RTS, and OUT2 in the MCR */ XIo_Out8(UART_BASEADDR + XUN_MCR_OFFSET, XUN_MCR_OUT_2 | XUN_MCR_RTS | XUN_MCR_DTR);

xil_printf("\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n");

xil_printf("Starting Up...\n");

xil_printf("Console: 16550 initialized.\n");

/*------------------------------------------------------------------*/ /* Do LWIP System Inits */ /*---------------------------------------------------------------*/

#ifdef STATS stats_init();

#endif /* STATS */ xil_printf("Initializing Memory Structures."); sys_init(); mem_init(); xil_printf("."); memp_init(); xil_printf("."); pbuf_init(); xil_printf(" done.

\n");

Page 157: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 157UG114 (v3.0) June 22, 2004 1-800-255-7778 Embedded Development Kit

Example lwIP ApplicationR

// set GPIO I/O Mask XGpio_mSetDataDirection(XPAR_MYGPIO_BASEADDR, 0x00000FFF);

// Turn on 4 LEDs (Active Low) XGpio_mSetDataReg(XPAR_MYGPIO_BASEADDR, 0x00000000);

/*---------------------------------------------------------------*//* Initial Header and Menus. Do this before the netif_init() so we

can */ /* change the MAC Address and IP addresses if needed */ /*---------------------------------------------------------------*/ while(init_wait--); print_app_header();

fullmac[0] = XILINX_MAC_OUI0; fullmac[1] = XILINX_MAC_OUI1; fullmac[2] = XILINX_MAC_OUI2; fullmac[3] = low_mac[0]; fullmac[4] = low_mac[1]; fullmac[5] = low_mac[2];/*---------------------------------------------------------------*/

/* Set host addresses */ /*---------------------------------------------------------------*/xemacif_setmac(0, (u8_t *) fullmac); //Set MAC IP4_ADDR(&gw, gateway[0],gateway[1],gateway[2],gateway[3]); //Set

gatewayIP4_ADDR(&ipaddr, ip[0],ip[1],ip[2],ip[3]); //Set ip IP4_ADDR(&netmask,subnet[0],subnet[1],subnet[2],subnet[3]); //Set

subnet msk

/*---------------------------------------------------------------*/

/* Show some host boot stuff and parameters */ /*---------------------------------------------------------------*/ xil_printf("

\nStarting Network Interface...\n");

xil_printf(" MAC Address: "); show_dashed_hex(6, fullmac);xil_printf("\n");

xil_printf(" IP Address: "); show_dotted_decimal(ip);xil_printf("\n");

xil_printf(" Subnet Mask: "); show_dotted_decimal(subnet);xil_printf("\n");

xil_printf(" Gateway IP: "); show_dotted_decimal(gateway);xil_printf("\n");

Page 158: Edk Libs Ref Guide

158 www.xilinx.com EDK OS and Libraries Reference GuideEmbedded Development Kit 1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 11: lwIP LibraryR

xil_printf(" Echo Port: 7\n");

/*---------------------------------------------------------------*/

/* Initialize netif */ /*---------------------------------------------------------------*/ netif_init();

/*---------------------------------------------------------------*/

/* Initialize TCP Stack */ /*---------------------------------------------------------------*/ tcp_init();

/*---------------------------------------------------------------*/

/* Set up the lwIP network interface... */ /*---------------------------------------------------------------*/ default_netif = netif_add(&ipaddr,

&netmask, &gw, &XEmacIf_ConfigTable[0], xemacif_init, ip_input

);

netif_set_default(default_netif);

/*---------------------------------------------------------------*/ /* create new tcp pcb and start applications */ /*---------------------------------------------------------------*/

// Start the Server xil_printf("Echo Server Running ... "); xil_printf("

\n"); echo_init(); app_running = 1;

while (1) { while (waiting_for_timer) {

xemacif_input(default_netif); } my_tmr(); waiting_for_timer = 1;

} return (1);}

int main ()

{ /*---------------------------------------------------------------*//* Enable instruction and data cache-this must be done first because

Page 159: Edk Libs Ref Guide

EDK OS and Libraries Reference Guide www.xilinx.com 159UG114 (v3.0) June 22, 2004 1-800-255-7778 Embedded Development Kit

Example lwIP ApplicationR

*/ /* the Memec Design Virtex-II Dev Boards (rev1 and rev2) have theSDRAM *//* byte enables tied together on the board. Enabling the caches

*/ /* guarantees that all memory accesses are 32-bit aligned. */ /*---------------------------------------------------------------*/

return main_main();}

void mytimer_int_handler (void* baseaddr_p) {

int baseaddr = *(int *)baseaddr_p; unsigned int csr; unsigned int gpio_data;

/* Read timer 0 CSR to see if it raised the interrupt */ csr = XTmrCtr_mGetControlStatusReg(XPAR_OPB_TIMER_1_BASEADDR, 0);

if (csr & XTC_CSR_INT_OCCURED_MASK) {

//xil_printf("Timer Handler ...\n"); waiting_for_timer = 0;

/* Clear the timer interrupt */ XTmrCtr_mSetControlStatusReg(XPAR_OPB_TIMER_1_BASEADDR, 0, csr); }}

FileName : echo.c echo.h These are the same files as used in the PowerPC example described above.

For MicroBlaze design, the echo server application is set to start at 0x86000000 which is the start address of SDRAM. The entire design runs off the external memory.

Page 160: Edk Libs Ref Guide

160 www.xilinx.com EDK OS and Libraries Reference GuideEmbedded Development Kit 1-800-255-7778 UG114 (v3.0) June 22, 2004

Chapter 11: lwIP LibraryR