EDK OS and Libraries

Reference Guide

Embedded Development Kit

EDK 6.2i

UG114 (v3.0) June 22, 2004

R
 R

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

EDK OS and Libraries Reference Guide www.xilinx.com UG114 (v3.0) June 22, 2004
1-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.

UG114 (v3.0) June 22, 2004 www.xilinx.com EDK OS and Libraries Reference Guide
1-800-255-7778
EDK OS and Libraries Reference Guide www.xilinx.com UG114 (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 Contents
This book contains the following chapters.
x Chapter 1, “Introduction”
x Chapter 2, “Xilinx Microkernel (XMK)”
x Chapter 3, “LibXil Standard C Libraries”
x Chapter 4, “Standalone Board Support Package”
x Chapter 5, “Xilkernel”
x Chapter 6, “LibXil Net”
x Chapter 7, “LibXil File”
x Chapter 8, “LibXil FATFile System (FATfs)”
x Chapter 9, “LibXil Memory File System (MFS)”
x Chapter 10, “LibXil Profile”

Additional Resources
For 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

EDK OS and Libraries Reference Guide www.xilinx.com 5

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Preface: About This Guide

Resource Description/URL
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

Conventions
This document uses the following conventions. An example illustrates each convention.

Typographical
The following typographical conventions are used in this document:

Convention Meaning or Use Example

Messages, prompts, and
Courier font program files that the system speed grade: - 100
displays
Literal commands that you
Courier bold ngdbuild design_name
enter in a syntactical statement
Commands that you select
File o Open
Helvetica bold from a menu
Keyboard shortcuts Ctrl+C
Variables in a syntax
statement for which you must ngdbuild design_name
supply values
See the Development System
Italic font References to other manuals Reference Guide for more
information.
If a wire is drawn so that it
Emphasis in text overlaps the pin of a symbol,
the two nets are not connected.

6 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Conventions

Convention Meaning or Use Example

An optional entry or
parameter. However, in bus ngdbuild [option_name]
Square brackets [ ]
specifications, such as design_name
bus[7:0], they are required.
A list of items from which you
Braces { } lowpwr ={on|off}
must choose one or more
Separates items in a list of
Vertical bar | lowpwr ={on|off}
choices
IOB #1: Name = QOUT’
Vertical ellipsis
IOB #2: Name = CLKIN’
. Repetitive material that has
.
. been omitted
.
.
.
Repetitive material that has allow block block_name
Horizontal ellipsis . . .
been omitted loc1 loc2 ... locn;

Online Document
The following conventions are used in this document:

Convention Meaning or Use Example

See the section “Additional
Cross-reference link to a Resources” for details.
Blue text location in the current
document Refer to “Title Formats” in
Chapter 1 for details.
Cross-reference link to a See Figure 2-5 in the Virtex-II
Red text
location in another document Handbook.
Go to http://www.xilinx.com
Blue, underlined text Hyperlink to a website (URL)
for the latest speed files.

EDK OS and Libraries Reference Guide www.xilinx.com 7

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Preface: About This Guide

8 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
Table of Contents

Preface: About This Guide

Guide Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Additional Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Typographical . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Online Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Chapter 1: Introduction

Chapter 2: Xilinx Microkernel (XMK)

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
XMK Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Chapter 3: LibXil Standard C Libraries

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Standard C Library (libc.a) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Xilinx C Library (libxil.a) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Input/Output Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Memory Management Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
MicroBlaze Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
PowerPC 405 Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Arithmetic Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
MicroBlaze Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Integer Arithmetic. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Floating Point Arithmetic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
PowerPC 405 Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Integer Arithmetic. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Floating Point Arithmetic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Chapter 4: Standalone Board Support Package

MicroBlaze BSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Interrupt Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
void microblaze_enable_interrupts(void) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
void microblaze_disable_interrupts(void) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Instruction Cache Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
void microblaze_enable_icache(void) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
void microblaze_disable_icache(void) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
void microblaze_update_icache (int tag, int instr, int lock_valid) . . . . . . . . . . . . . . . . . 26
void microblaze_init_icache_range (int cache_addr, int cache_size) . . . . . . . . . . . . . . . 26
Data Cache Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
void microblaze_enable_dcache(void) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
void microblaze_disable_dcache(void) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

EDK OS and Libraries Reference Guide www.xilinx.com 9

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

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

void microblaze_init_dcache_range (int cache_addr, int cache_size) . . . . . . . . . . . . . . . 27
Fast Simplex Link Interface Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
microblaze_bread_datafsl(val, id) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
microblaze_bwrite_datafsl(val, id) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
microblaze_nbread_datafsl(val, id) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
microblaze_nbwrite_datafsl(val, id) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
microblaze_bread_cntlfsl(val, id) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
microblaze_bwrite_cntlfsl(val, id). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
microblaze_nbread_cntlfsl(val, id) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
microblaze_nbwrite_cntlfsl(val, id) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
PowerPC BSP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Boot Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
boot.S . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
crt0.S . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
eabi.S . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
void XCache_WriteCCR0(unsigned int val);. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
void XCache_EnableDCache(unsigned int regions);. . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
void XCache_DisableDCache(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
void XCache_FlushDCacheLine(unsigned int adr); . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
void XCache_StoreDCacheLine(unsigned int adr);. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
void XCache_EnableICache(unsigned int regions); . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
void XCache_DisableICache(void);. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
void XCache_InvalidateICache(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
void XCache_InvalidateICacheLine(unsigned int adr); . . . . . . . . . . . . . . . . . . . . . . . . . 30
Exception Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
void XExc_Init(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
void XExc_RegisterHandler(Xuint8 ExceptionId, XExceptionHandler Handler, void *DataPtr);31
void XExc_RemoveHandler(Xuint8 ExceptionId). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
void XExc_mEnableExceptions (EnableMask); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
void XExc_mDisableExceptions (DisableMask); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
int read(int fd, char *buf, int nbytes); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
int write(int fd, char *buf, int nbytes); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
int isatty(int fd); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
char *sbrk(int nbytes); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Processor-Specific Include Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
typedef unsigned long long XTime; . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
void XTime_SetTime(XTime xtime); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
void XTime_GetTime(XTime *xtime); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
void XTime_TSRClearStatusBits(unsigned long Bitmask); . . . . . . . . . . . . . . . . . . . . . . . 33
void XTime_PITSetInterval(unsigned long interval); . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
void XTime_PITEnableInterrupt(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
void XTime_PITDisableInterrupt(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
void XTime_PITEnableAutoReload(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
void XTime_PITDisableAutoReload(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
void XTime_PITClearInterrupt(void); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
unsigned int usleep(unsigned int __useconds); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
unsigned int sleep(unsigned int __seconds); . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

10 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

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

Chapter 5: Xilkernel
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Key Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Xilkernel Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Xilkernel Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Building Xilkernel Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Xilkernel Process Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Xilkernel Scheduling Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Xilkernel API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Process Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Thread Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Semaphores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Message Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Shared Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Mutex Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Dynamic Block Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Interrupt Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Kernel Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Customizing STDIN and STDOUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Customizing User Initialization Routine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Customizing Process Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Customizing Scheduling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Customizing Thread Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Customizing Semaphore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Customizing Message Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Customizing Shared Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Customizing Pthread Mutex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Customizing Dynamic Block Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Customizing Linker Script (PPC405) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Configuring System Timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Configuring Interrupt Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Configuring Debug Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Copy Kernel Source Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Debugging Xilkernel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Memory Footprint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Xilkernel File Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
System Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Future Enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Modifying Xilkernel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
User Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Chapter 6: LibXil Net

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
LibXilNet Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

EDK OS and Libraries Reference Guide www.xilinx.com 11

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Quick Glance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Protocols Supported . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Library Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Protocol Function Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Media Access Layer (MAC) Drivers Wrapper. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Ethernet Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
ARP (RFC 826) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
IP (RFC 791) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
ICMP (RFC 792) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
UDP (RFC 768) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
TCP (RFC 793) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Sockets API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Buffer Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Current Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Functions of LibXilNet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
LibGen Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Using XilNet in Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Chapter 7: LibXil File

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Module Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Module Routines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Libgen Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
LibXil File Instantiation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
System Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Chapter 8: LibXil FATFile System (FATfs)

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
XilFatfs Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
Detailed Description of XilFatfsFunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
LibGen Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

Chapter 9: LibXil Memory File System (MFS)

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
MFS Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Quick Glance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Detailed summary of MFS Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Utility Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Additional Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
C-like access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
LibGen Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

Chapter 10: LibXil Profile

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

12 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Profiling Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Customizing xilprofile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Building Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
124
Application Memory Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Generating GPROF Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
XilProfile Code Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Chapter 11: lwIP Library

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
PowerPC System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
MicroBlaze System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Setting Up lwIP in EDK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
libgen Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Designing an lwIP Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Initializing lwIP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
lwIP Raw API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Raw APO Functions for TCP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Example lwIP Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
PowerPC based Echo Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
C Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
MicroBlaze-Based Echo Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
C Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

EDK OS and Libraries Reference Guide www.xilinx.com 13

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

14 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Chapter 1

Introduction
This book describes the software packages that are provided by the Embedded
Development Kit. EDK supplies libraries, board support packages, and complete
operating systems, in addition to the drivers for the peripherals, to help the user develop a
software platform. The following is the distribution of the software packages available for
the user to include in his platform:
x Xilinx Micro-Kernel (XMK) - XMK is the entity representing the collective software
system formed by the following components,
i Standard C Libraries (libc, libm)
i Xilkernel - An embedded kernel
i Standalone Board Support Package (BSP)
i LibXil Net - A networking library
i LibXil MFS - A Memory File System
i LibXil File - A file I/O library
i LibXil Drivers - Device drivers for supported peripherals
x 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 the
Xilnet and Xilfile libraries, along with the Xilkernel operating system.
This guide documents the Xilinx Micro-kernel, its constituent libraries and the Standalone
board-support package. Documentation for the other operating systems can be found in
their respective reference guides. Device drivers are documented along with the
corresponding peripheral’s documentation.

EDK OS and Libraries Reference Guide www.xilinx.com 15

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 1: Introduction

Figure 1-1: Software Platform Settings in XPS

16 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 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.
x “Overview”
x “XMK Organization”

Overview
There 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,
x LibXil Driver - Xilinx device drivers
x LibXil Net - Xilinx networking support
x LibXil File - Xilinx file I/O functions
x LibXil MFS - Xilinx memory file system
x 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 Organization
The 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

EDK OS and Libraries Reference Guide www.xilinx.com 17

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 2: Xilinx Microkernel (XMK)

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.

User Application
libc

stdio

stdlib

LibXil string
Xil Kernel LibXil Net LibXil File LibXil Mfs
Profile
Other

libm

Standalone BSP LibXil Driver

Hardware X10143

Figure 2-1: XMK Structure

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

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

18 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

XMK Organization

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.

EDK OS and Libraries Reference Guide www.xilinx.com 19

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 2: Xilinx Microkernel (XMK)

20 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Chapter 3

LibXil Standard C Libraries

This chapter describes the software libraries available for the embedded processors. The
chapter contains the following sections.
x “Overview”
x “Standard C Library (libc.a)”
x “Xilinx C Library (libxil.a)”
x “Input/Output Functions”
x “Memory Management Functions”
x “Arithmetic Operations”

Overview
The 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
x processor = powerpc-eabi or microblaze
x platform = sol, nt or lin
x 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

EDK OS and Libraries Reference Guide www.xilinx.com 21

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 3: LibXil Standard C Libraries

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.o
xil_malloc.o
xil_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 Functions
The 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.

22 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Memory Management Functions

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 Processor
Memory 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 include
xil_malloc, xil_free and xil_calloc function. In the Standalone OS block, if the
PARAMETER need_xil_malloc is set to TRUE, calls to malloc result in a call to
xil_malloc and the same for free and calloc. These functions are a lighter version of the
newlib 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 Processor

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

EDK OS and Libraries Reference Guide www.xilinx.com 23

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 3: LibXil Standard C Libraries

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.

24 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 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.
x “MicroBlaze BSP”
x “PowerPC BSP”

MicroBlaze BSP
When 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 Handling
The 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 Handling

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

EDK OS and Libraries Reference Guide www.xilinx.com 25

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 4: Standalone Board Support Package

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.

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.

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 Handling

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

26 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

MicroBlaze BSP

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 Macros

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

EDK OS and Libraries Reference Guide www.xilinx.com 27

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 4: Standalone Board Support Package

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 BSP
When 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 Code
The 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.

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

28 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

PowerPC BSP

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.

EDK OS and Libraries Reference Guide www.xilinx.com 29

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 4: Standalone Board Support Package

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

30 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

PowerPC BSP

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.

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

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

EDK OS and Libraries Reference Guide www.xilinx.com 31

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 4: Standalone Board Support Package

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.

Files
File support is limited to the stdin and stdout streams. In such an environment, the
following functions do not make much sense:
x open() (in open.c)
x close() (in close.c)
x fstat() (in fstat.c)
x unlink() (in unlink.c)
x 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.

32 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

PowerPC BSP

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.

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

Time
The 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

EDK OS and Libraries Reference Guide www.xilinx.com 33

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 4: Standalone Board Support Package

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:

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.

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.

34 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

PowerPC BSP

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

EDK OS and Libraries Reference Guide www.xilinx.com 35

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 4: Standalone Board Support Package

PARAMETER HW_INSTANCE = PPC405_i

PARAMETER DRIVER_NAME = cpu_ppc405
PARAMETER DRIVER_VER = 1.00.a
PARAMETER CORE_CLOCK_FREQ_HZ = 20000000
END
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 PROCESSOR
PARAMETER HW_INSTANCE = PPC405_i
PARAMETER DRIVER_NAME = cpu_ppc405
PARAMETER DRIVER_VER = 1.00.a
PARAMETER CORE_CLOCK_FREQ_HZ = 20000000
END
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.

36 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Chapter 5

Xilkernel
This chapter describes Xilkernel, a kernel for the Xilinx embedded processors. The chapter
contains the following sections.
x “Overview”
x “Key Features”
x “Xilkernel Blocks”
x “Xilkernel Modes”
x “Building Xilkernel Applications”
x “Xilkernel Process Model”
x “Xilkernel Scheduling Model”
x “Xilkernel API”
x “Interrupt Handling”
x “Kernel Customization”
x “Debugging Xilkernel”
x “Memory Footprint”
x “Xilkernel File Organization”
x “System Initialization”
x “Limitations”
x “Future Enhancements”
x “Modifying Xilkernel”
x “User Guide”

Overview
Xilkernel 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 Features
Xilkernel has the following notable features:
x An API closely supporting a subset of POSIX that targets embedded kernels.

EDK OS and Libraries Reference Guide www.xilinx.com 37

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 5: Xilkernel

x Kernel implementation of core functionality, such as

i Process Management
i Thread Management
i Synchronization services - Semaphores and Mutex Locks
i IPC services - Message Queues and Shared Memory
i Dynamic Block Memory Allocation
i User level interrupt handling API
x Highly scalable kernel that can be accommodated into a given system through the
inclusion or exclusion of functionality as required.
x Easy kernel configuration with XPS, MLD, and MSS mechanisms.
x Support for static task undesired specification.
x Configurable scheduling - priority-driven preemptive scheduling or round-robin
scheduling.
x System call interface to the kernel.

Xilkernel Blocks
The 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.

Xilkernel Modules

User Application
User Interrupts
Eg. Webserver

System Call Timer Interrupt for

Library Context Switch

Xilkernel

System Call Handler Scheduler Interrupt Handler

Thread Process
Semaphores
Management Management

Message Shared Dynamic Buffer

Queue Memory Management

X10131

Figure 5-1: Xilernel Modules

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

38 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Xilkernel Modes

Xilkernel Modes
Xilkernel and user applications can be built in two different modes:
x 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/pthreads
configuration, using the parameters separate_exec_process_table and
separate_exec_pthread_table in libgen configuration. Applications can get services
from the kernel using the system call interface. These system call wrappers can be
obtained by linking the application with libsyscall.a.This mode provides the flexibility
of developing and dynamically loading each application separately. The stack for the
user application will have to be separately setup as a part of each elf file and the kernel
does no special stack setup. xilkernel.elf is generated only if the process contexts are not
configured in the next mode in the OS specification.
x Kernel Bundled Executable mode
In this mode, the user applications and kernel are bundled and built together as a
single executable elf file. The entry point for an application is a function name that is
specified using parameters kernel_bundled_process_table and
kernel_bundled_pthread_table in the MSS. Building xilkernel using libgen generates
libxilkernel.a library. This can be linked with all the user applications which need to run
on xilkernel, to generate a single kernel bundled executable. Since all the user
applications are part of a single executable, symbol names, such as global variables
and function names, should be unique. Though user applications can directly call the
sys_ prefixed system calls, they would have to lock and unlock the kernel before
calling the system calls. To simplify this process, applications in single executable
mode 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 on
behalf of the single elf applications.The kernel bundled executable mode is a superset of
the separate executable mode. Applications that are separate executables can still
interface with the single executable kernel image dynamically, using the system call
API in libsyscall.a. These system calls will be handled by the system call handlers that
are present in the kernel image.Building and linking applications in the two xilkernel
modes is illustrated in Figure 5-2.

Building Xilkernel Applications

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

EDK OS and Libraries Reference Guide www.xilinx.com 39

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 5: Xilkernel

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.

Kernel Sources

Separate Executable Mode Kernel Bundled Executable Mode

libsyscall.a libxilkernel.a

xilkernel.elf

User Sources User Sources

+ libsyscall.a Executable + libxilkernel.a

+ libsyscall.a Executable

Kernel Bundled
Kernel and Application Application
.elf files X10129

Figure 5-2: Building Applications for Xilkernel

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.

40 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Xilkernel Process Model

Pure Separate Executable Mode Scenario Kernel Bundled Executable Mode Scenario

User Space User Space

Proc1 Proc2 Proc3 Proc4 Proc5 Proc6

System Call Handler Proc1 System Call Handler

System Call
Wrappers
Proc2
xilkernel.elf libxilkernel.a
Proc3

Kernel Image
Kernel Image
X10128

Figure 5-3: Xilkernel System Call Interface

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 Model

Xilkernel 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

EDK OS and Libraries Reference Guide www.xilinx.com 41

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 5: Xilkernel

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

Xilkernel Scheduling Model

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

Active
0 A

1
B C D
2
(Blocked)
Priority

13 E

14 F
G
15
(Blocked)
X10132

Figure 5-4: Priority Driven Scheduling

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

x PROC_NEW
x PROC_READY
x PROC_RUN
x PROC_WAIT
x PROC_DEAD
The process context state diagram is shown in Figure 5-5.

42 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Xilkernel API

Activated Terminated

PROC_NEW PROC_RUN PROC_DEAD

in
led

Blo
du

cke
he

d
Sc

t
ou

ted
Un
led

ina
blo
du

rm
c
he

ke

Te
Sc

d
PROC_READY PROC_WAIT

ed
at
in
rm
Unblocked

Te
X10130

Figure 5-5: Process Context States

Xilkernel API

Process Management
A 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.

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

EDK OS and Libraries Reference Guide www.xilinx.com 43

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 5: Xilkernel

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:
i pid is the process ID
i 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

44 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Xilkernel API

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

Thread Management
Xilkernel 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

EDK OS and Libraries Reference Guide www.xilinx.com 45

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 5: Xilkernel

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

46 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Xilkernel API

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

EDK OS and Libraries Reference Guide www.xilinx.com 47

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 5: Xilkernel

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

48 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Xilkernel API

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

EDK OS and Libraries Reference Guide www.xilinx.com 49

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 5: Xilkernel

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

Semaphores
Xilkernel 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 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

50 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Xilkernel API

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

EDK OS and Libraries Reference Guide www.xilinx.com 51

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 5: Xilkernel

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

52 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Xilkernel API

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

EDK OS and Libraries Reference Guide www.xilinx.com 53

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 5: Xilkernel

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

54 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Xilkernel API

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

Message Queues
Xilkernel 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

EDK OS and Libraries Reference Guide www.xilinx.com 55

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 5: Xilkernel

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:
x msg_qnum, msg_lspid, msg_lrpid are set equal to 0.
x 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

56 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Xilkernel API

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

EDK OS and Libraries Reference Guide www.xilinx.com 57

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 5: Xilkernel

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:
x The condition responsible for the suspension no longer exists,
in which case the message is sent.
x 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

58 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Xilkernel API

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:
i A message is placed on the queue.
i 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:
i msg_qnum is decremented by 1.
i msg_lrpid is set equal to the process ID of the calling process.

Includes sys/msg.h
sys/ipc.h

Shared Memory
Xilkernel 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.

EDK OS and Libraries Reference Guide www.xilinx.com 59

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 5: Xilkernel

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:
x The argument key is equal to IPC_PRIVATE.
x 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

60 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Xilkernel API

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

EDK OS and Libraries Reference Guide www.xilinx.com 61

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 5: Xilkernel

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

Mutex Locks
Xilkernel 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

62 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Xilkernel API

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

EDK OS and Libraries Reference Guide www.xilinx.com 63

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 5: Xilkernel

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

64 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Xilkernel API

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

Dynamic Block Memory Management

The 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

EDK OS and Libraries Reference Guide www.xilinx.com 65

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 5: Xilkernel

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.

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

Interrupt Handling
Xilkernel 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

66 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Interrupt Handling

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

Interrupts/
Exceptions
Enabled

Task Code
Interrupted

Save volatile registers timer_int_handler( )

Interrupts/
interrupt vectoring code process_scheduler( );
Exceptions
IF context switch required THEN
Disabled
XMK_CONTEXT_SWITCH( );

Restore volatile registers Return in the context

Interrupts/
of the "next" task
Exceptions
Enabled

Next Task
Proceeds X10141

Figure 5-6: Basic Interrupt Service in Xilkernel

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

EDK OS and Libraries Reference Guide www.xilinx.com 67

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 5: Xilkernel

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

IE = 1

Task Code
Gets
Interrupted
_ _interrupt_handler( )
IE = 0 save volatile registers
intc_device_interrupt_handler( ); intc_device_interrupt_handler( )
1. Determine source of interrupts
2. Service ALL interrupt requests
3. IF process_scheduler( ) invoked on
a timer interrupt THEN
Do a context switch if required

Restore saved registers Return in the context

IE = 1 of the "next" task
Next Task
Proceeds

IE = 1
X10140

Figure 5-7: Extended Interrupt Service in Xilkernel

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

68 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Interrupt Handling

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>

EDK OS and Libraries Reference Guide www.xilinx.com 69

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 5: Xilkernel

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>

Kernel Customization
Xilkernel 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)

70 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Kernel Customization

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 = 5
PARAMETER config_pthread_mutex = true
PARAMETER config_malloc = true
PARAMETER mem_table = ((4,10), (3,10),(8,10))
PARAMETER pit_interval = 0xffffff
PARAMETER copyoutfiles = true
PARAMETER 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 STDOUT

The 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

Attribute Description Type Defaults

stdin Instance name of stdin
string none
peripheral
stdout Instance name of
string none
stdout peripheral

Customizing User Initialization Routine

A 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

EDK OS and Libraries Reference Guide www.xilinx.com 71

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 5: Xilkernel

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

Attribute Description Type Defaults

user_init Invoke user_init during
boolean false
system initialization.

Customizing Process Management

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

Table 5-3: Process management parameters

Attribute Description Type Defaults
config_process Need process management boolean true
max_procs Maximum number of
numeric 10
processes in the system
max_readyq Maximum size of Ready
numeric 10
queue for each priority
config_process_kill Include process_kill() function boolean false
config_process_kill Include process_kill() function boolean false
config_process_sleep Include process_sleep()
boolean false
function
separate_exec_process_table Configure startup processes
that are separate executable
files. This is defined to be an array of 2-
none
array with each element tuples
containing the parameters
process_start and process_prio.
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 array of 3-
none
containing the parameters tuples
process_start_func,
process_prio, and
process_stack_size.
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

72 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Kernel Customization

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

Table 5-4: Scheduling parameters

Attribute Description Type Defaults
config_sched Configure scheduler
boolean true
module
sched_type Type of Scheduler to be
used. Allowed values 2
numeric
x 2 - SCHED_RR (SCHED_RR)
x 3 - SCHED_PRIO
n_prio Number of priority
levels if scheduling is numeric 32
SCHED_PRIO.

Customizing Thread Management

The 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-5: Thread module parameters

Attribute Description Type Defaults
config_pthread_support Need pthread module boolean false
max_pthreads Maximum number of
numeric 5
threads
pthread_stack_size Stack size for dynamically
numeric 600
created threads (in bytes)
separate_exec_pthread_table Configure startup threads
that are also separate
executable files. This is
defined to be an array array of
none
with each element 2-tuples
containing the parameters
pthread_start and
pthread_prio.
kernel_bundled_pthread_table Configure startup threads
that are a part of the kernel
bundle. This is defined to
be an array with each array of
none
element containing the 2-tuples
parameters
pthread_start_func and
pthread_prio.
pthread_start Thread start address address none

EDK OS and Libraries Reference Guide www.xilinx.com 73

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 5: Xilkernel

Table 5-5: Thread module parameters

Attribute Description Type Defaults
pthread_start_func Thread start function string none
process_prio Thread priority numeric none

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

Table 5-6: Semaphore module parameters

Attribute Description Type Defaults
config_sema Need Semaphore module boolean false
max_sem Maximum number of
numeric 10
Semaphores
max_sem_waitq Semaphore Wait Queue
numeric 10
Length

Customizing Message Queue

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

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
numeric 10
the system
msgq_capacity Maximum number of messages
numeric 10
in the queue

Customizing Shared Memory

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

74 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Kernel Customization

Table 5-8: Shared Memory Module Parameters

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
array of 1-tuples none
element having shm_size
parameter
shm_size Shared Memory size numeric none
num_shm Number of Shared Memories -
numeric none
Size of the shm_table array.

Customizing Pthread Mutex

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

Table 5-9: Pthread mutex Module Parameters

Attribute Description Type Defaults
config_pthread_mutex Need pthread mutex
boolean false
module
max_pthread_mutex Maximum number
of pthread mutex
numeric 5
locks available in the
system.
max_pthread_mutex_ waitq Length of each the
mutex lock wait numeric 10
queue.

Customizing Dynamic Block Memory Management

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

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 array of 2-tuples none
mem_bsize, mem_nblks
parameters.
mem_bsize Memory block size. numeric none

EDK OS and Libraries Reference Guide www.xilinx.com 75

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 5: Xilkernel

Table 5-10: Memory Management module parameters

Attribute Description Type Defaults
mem_nblks Number of memory blocks
numeric none
of a size
n_malloc_blocks Number of memory blocks
configurations - Size of numeric none
mem_table array

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.

Table 5-11: Linker Script Configuration parameters in PPC405

Attribute Description Type Defaults
linker_script_specification Need Custom Linker
boolean false
Script specification
vect_mem_start Start address of Vector
address 0x0
Table Program section.
vect_mem_size Size of Vector table numeric-
9K
section. Specify as xK. size
code_mem_start Start address of Code
address 0xffffd000
section.
code_mem_size Size of Code section. numeric-
12K
Specify as xK. size
data_mem_start Start address of Data
address 0x2400
section.
data_mem_size Size of Data section. numeric-
9K
Specify as xK. size

76 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Kernel Customization

Configuring System Timer

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

Table 5-12: Attributes for Copying Kernel Source Files

Attribute Description Type Defaults
systmr_spec A tuple specifying the timer device
(MicroBlaze only) instance name and the timer type.
2-tuple of
For example, (system_timer, PIT). null
(string, string)
PIT and FIT are the only supported
timer type strings.
pit_interval Specify the count down interval for
the PIT timer in PPC and the PIT numeric 0xffffff
timer in MicroBlaze, if so configured.

Configuring Interrupt Handling

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

Table 5-13: Attributes for Copying Kernel Source files

Attribute Description Type Defaults
sysintc_spec Specify the instance name of the
interrupt controller device
string null
connected to the external interrupt
port.

Configuring Debug Messages

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

Attribute Description Type Defaults

debug_mode Turn on debug messages
boolean false
from the kernel.

EDK OS and Libraries Reference Guide www.xilinx.com 77

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 5: Xilkernel

Copy Kernel Source Files

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

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>/ path string “.”
libsrc/xilkernel_v2_00_a/src
directory
copytodir User repository directory. The
path is relative to
"../../../copyof
<project_direc>/<systemname>/ path string
lib"
libsrc/xilkernel_v2_00_a/src
directory

Debugging Xilkernel
In 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 Footprint
The 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-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 ~4.5 ~12.5
(no threads)

78 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Xilkernel File Organization

Table 5-15: User Configuration and Xilkernel Size

Configuration MicroBlaze (in Kb) PPC (in Kb)
Basic kernel functionality
with multi-tasking and ~7.4 ~15.7
multi-threading.
Full kernel functionality
with all modules (processes,
threads, support for both separate
and kernel bundled applications,
~19.3 24.1
IPC, synchronization constructs,
malloc, interrupt handling,
drivers for interrupt controller
and timer)

Xilkernel File Organization

Xilkernel 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 Initialization
The 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

EDK OS and Libraries Reference Guide www.xilinx.com 79

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 5: Xilkernel

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.

Limitations
Xilkernel currently has the following limitations.
x 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.
x Timer support is not complete in both versions of Xilkernel.
x POSIX error reporting structure is not fully complete. Therefore, the errno feature is
not supported in the POSIX calls.
x 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 Enhancements
Apart from overcoming the above limitations, future enhancements will focus on
supporting the following features.
x Memory protection (with some hardware support).
x Better memory allocation and memory mapping functionality.
x Preventing priority inversion with priority inheritance.
x Supporting debugging of separate executable applications with GDB.
x Alarms and Timers.
x Migrating to POSIX scheduling schemes (SCHED_FIFO and SCHED_RR schemes in a
common priority based implementation).
x POSIX signals.

Modifying Xilkernel
Users 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 Guide
Refer 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

80 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

User Guide

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.

EDK OS and Libraries Reference Guide www.xilinx.com 81

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 5: Xilkernel

82 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 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.
x “Overview”
x “LibXilNet Functions”
x “Protocols Supported”
x “Library Architecture”
x “Protocol Function Description”
x “Current Restrictions”
x “Functions of LibXilNet”
x “LibGen Customization”
x “Using XilNet in Application”

Overview
The 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 Glance
Table 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)

EDK OS and Libraries Reference Guide www.xilinx.com 83

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 6: LibXil Net

Table 6-1: LibXilNet functions at a glance

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

84 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Protocols Supported

Table 6-1: LibXilNet functions at a glance

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

Protocols Supported
LibXilNet supports drivers and functions for the Sockets API and protocols of TCP/IP
stack. The following list enumerates them.
x Ethernet Encapsulation (RFC 894)
x Address Resolution Protocol (ARP - RFC 826)
x Internet Protocol (IP - RFC 791)
x Internet Control Management Protocol (ICMP - RFC 792)
x Transmission Control Protocol (TCP - RFC 793)
x User Datagram Protocol (UDP - RFC 768)
x Sockets API

Library Architecture
Figure 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

EDK OS and Libraries Reference Guide www.xilinx.com 85

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 6: LibXil Net

PING Application HTTP Server Application TFTP Application

Xilinx Sockets Interface

Demultiplexing
based on
connections
ICMP TCP UDP

Demultiplexing based
on protocal value in
IP Header
ARP IP

Demultiplexing based on
frame type in Ethernet Header

Ethernet
Driver

Incoming Frame

MAC
Driver

From PHY Interface

LibXilNet Architecture

UG111_07_111903

Figure 6-1: Schematic Diagram of LibXilNet Architecture

86 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Protocol Function Description

Protocol Function Description

A detailed description of the drivers and the protocols supported is given below.

Media Access Layer (MAC) Drivers Wrapper

MAC 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 Drivers
Ethernet 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

EDK OS and Libraries Reference Guide www.xilinx.com 87

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 6: LibXil Net

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 API
Functions 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 Management
XiNet 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
x Only server functionalities for ARP - This means ARP requests are not being
generated from the processor
x Only server functionalities in libXilNet - This means no client application
development support provided in libXilNet.
x 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 LibXilNet
The following table gives the list of functions in libXilNet and their descriptions

88 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Functions of LibXilNet

int xilsock_init (void)

Parameters None
Returns 1 for success and 0 for failure
Description Initialize the xilinx internal sockets for use.
Includes xilsock.h

void xilsock_rel_socket (int sd)

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

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

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

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

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

EDK OS and Libraries Reference Guide www.xilinx.com 89

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 6: LibXil Net

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

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

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

Parameters s: UDP socket descriptor

buf: Buffer to receive data
len: Buffer size
Returns Number of bytes received
Receives data (maximum length of len) from the UDP socket s in
Description
buf and returns the number of bytes received.
Includes xilsock.h

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

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

90 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Functions of LibXilNet

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

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

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

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

void xilsock_close (int s)

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

void xilnet_mac_init (unsigned int baseaddr)

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

EDK OS and Libraries Reference Guide www.xilinx.com 91

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 6: LibXil Net

void xilnet_eth_init_hw_addr (unsigned char* addr)

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

int xilnet_eth_recv_frame (unsigned char* frame, int len)

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

void xilnet_eth_send_frame (unsigned char* frame, int len, unsigned

char* dipaddr, void *dhaddr, unsigned short type)

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

92 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Functions of LibXilNet

void xilnet_eth_update_hw_tbl (unsigned char* frame, int proto)

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

void xilnet_eth_add_hw_tbl_entry (unsigned char* ip, unsigned char*

hw)

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

int xilnet_eth_get_hw_addr (unsigned char* ip)

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

EDK OS and Libraries Reference Guide www.xilinx.com 93

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 6: LibXil Net

void xilnet_eth_init_hw_addr_tbl (void)

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

int xilnet_arp (unsigned char* buf, int len)

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

void xilnet_arp_reply (unsigned char* buf, int len)

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

void xilnet_ip_init (unsigned char* ip_addr)

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

94 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Functions of LibXilNet

int xilnet_ip (unsigned char* buf, int len)

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

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

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

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

int proto)

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

EDK OS and Libraries Reference Guide www.xilinx.com 95

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 6: LibXil Net

int xilnet_udp (unsigned char* buf, int len)

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

void xilnet_udp_header (struct xilnet_udp_conn conn, unsigned char*

buf, int len)

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

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

96 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Functions of LibXilNet

void xilnet_udp_init_conns (void )

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

int xilnet_udp_open_conn (unsigned short port)

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

int xilnet_udp_close_conn (struct xilnet_udp_conn *conn)

Parameters conn: UDP connection

Returns 1 if able to close else returns -1.
Description Close a UDP connection conn.
Includes xilsock.h

int xilnet_tcp (unsigned char* buf, int len)

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

EDK OS and Libraries Reference Guide www.xilinx.com 97

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 6: LibXil Net

void xilnet_tcp_header (struct xilnet_tcp_conn conn, unsigned char*

buf, int len)

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

void xilnet_tcp_send_pkt (struct xilnet_tcp_conn conn, unsigned

char* buf, int len, unsigned char flags)

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

void xilnet_tcp_init_conns (void )

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

int xilnet_tcp_open_conn (unsigned short port)

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

98 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

LibGen Customization

int xilnet_tcp_close_conn (struct xilnet_tcp_conn *conn)

Parameters conn: TCP connection

Returns 1 if able to close else returns -1.
Description Close a TCP connection conn.
Includes xilsock.h

int xilnet_icmp (unsigned char* buf, int len)

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

void xilnet_icmp_echo_reply (unsigned char* buf, int len)

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

LibGen Customization
XilNet library is customized through LibGen tool. Here is a snippet from system.mss file
for specifying LibXilNet.
BEGIN LIBRARY
PARAMETER LIBRARY_NAME = xilnet
PARAMETER LIBRARY_VER = 1.00.a
PARAMETER device_type = ethernet
PARAMETER emac_type = emac
END

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.

EDK OS and Libraries Reference Guide www.xilinx.com 99

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 6: LibXil Net

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

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

Using XilNet in Application

Libgen 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:
x Define “#include <net/xilnet_config.h>” in your C-file.
x Define “#include <net/xilsock.h>” in your C-file.

100 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 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.
x “Overview”
x “Module Usage”
x “Module Routines”
x “Libgen Support”
x “Limitations”

Overview
The 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 Usage
A 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)

EDK OS and Libraries Reference Guide www.xilinx.com 101

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 7: LibXil File

Functions
long lseek (int fd, long offset, int whence)
int chdir (const char *buf)
const char* getcwd (void)

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

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

int close (int fd)

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

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

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

102 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Module Routines

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

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

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

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

int chdir (char* newdir)

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

const char* getcwd (void)

Parameters None
Returns The current working directory.
Description Get the absolute path for the current working directory.
Includes xilfile.h
xparameters.h

EDK OS and Libraries Reference Guide www.xilinx.com 103

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 7: LibXil File

Libgen Support

LibXil File Instantiation

The 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
i <peripheral 1 name> : Instance name of the peripheral you need to access through
XilFile.
i <mount 1> : Mount name for the <peripheral 1> or <filesystem 1>
i <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 Initialization
LibGen 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.

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

104 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Limitations

x 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.
x Files cannot have names starting with /dev, since it is a reserved word to be used only
for accessing devices.
x Currently LibXil File has support only for 1 file system (LibXil Memory File System)
and 3 devices (UART, UARTlite and GPIO).
x Only devices can be assigned as STDIN, STDOUT and STDERR.

EDK OS and Libraries Reference Guide www.xilinx.com 105

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 7: LibXil File

106 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 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.
x “Overview”
x “XilFatfs Functions”
x “LibGen Customization”

Overview
The 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:
x OPB SYSACE Interface Controller - Logicore module
x SystemACE controller and CompactFlash connector
x 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 Functions
This section presents a list of functions provided by the XilFatfs. Table 8-1 provides the
function names with signature at a glance.

EDK OS and Libraries Reference Guide www.xilinx.com 107

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 8: LibXil FATFile System (FATfs)

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)

Detailed Description of XilFatfsFunctions

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

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

108 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

XilFatfs Functions

int sysace_fread (void *buffer, int size, int count, 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

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

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

int sysace_fclose (void *stream)

Parameters stream: File handle returned by sysace_fopen

Returns 1 On success
0 On failure
Description Closes an open file
Includes sysace_stdio.h

EDK OS and Libraries Reference Guide www.xilinx.com 109

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 8: LibXil FATFile System (FATfs)

int sysace_mkdir (const char *path)

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

int sysace_chdir (const char *path)

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

LibGen Customization
XilFatfs file system can be integrated with a system using the following snippet in the mss
file. There are
BEGIN LIBRARY
parameter LIBRARY_NAME = xilfatfs
parameter LIBRARY_VER = 1.10.a
# The following 3 parameters are optional and their default value is ‘n’
parameter CONFIG_WRITE = y
parameter CONFIG_DIR_SUPPORT = y
parameter CONFIG_FAT12 = y
END

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

110 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

LibGen Customization

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.

EDK OS and Libraries Reference Guide www.xilinx.com 111

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 8: LibXil FATFile System (FATfs)

112 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 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.
x “Overview”
x “MFS Functions”
x “Utility Functions”
x “Additional Utilities”
x “C-like access”
x “LibGen Customization”

Overview
The 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 Glance
This 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)

EDK OS and Libraries Reference Guide www.xilinx.com 113

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 9: LibXil Memory File System (MFS)

Table 9-1: MFS Functions at a Glance

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

114 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

MFS Functions

Detailed summary of MFS Functions

int mfs_init_fs (int numbytes, char *address, int status)

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

int mfs_change_dir (char *newdir)

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

int mfs_create_dir (char *newdir)

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

EDK OS and Libraries Reference Guide www.xilinx.com 115

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 9: LibXil Memory File System (MFS)

int mfs_delete_dir (char *dirname)

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

int mfs_get_current_dir_name (char *dirname)

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

int mfs_delete_file (char *filename)

Parameters filename: file to be deleted

Returns 1 for success
0 for failure
Description Delete filename from its directory.
Includes xilmfs.h

int mfs_rename_file (char *from_file, char *to_file)

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

116 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

MFS Functions

int mfs_exists_file (char *filename)

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

int mfs_get_usage (int *num_blocks_used, int *num_blocks_free)

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

int mfs_dir_open (char *dirname)

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

int mfs_dir_close (int fd)

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

EDK OS and Libraries Reference Guide www.xilinx.com 117

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 9: LibXil Memory File System (MFS)

int mfs_dir_read (int fd, char **filename, int *filesize, int

*filetype)

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

int mfs_file_open (char *filename, int mode)

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

int mfs_file_read (int fd, char *buf, int buflen)

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

118 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

MFS Functions

int mfs_file_write (int fd, char *buf, int buflen)

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

int mfs_file_close (int fd)

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

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

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

EDK OS and Libraries Reference Guide www.xilinx.com 119

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 9: LibXil Memory File System (MFS)

Utility Functions
The 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)

Parameters None
Returns On success return 1
On failure return 0
Description List contents of current directory on STDOUT.
Includes xilmfs.h

int mfs_cat (char *filename)

Parameters filename: File to be displayed

Returns On success return 1
On failure return 0
Description Print the file to STDOUT.
Includes xilmfs.h

int mfs_copy_stdin_to_file (char *filename)

Parameters filename: Destination file.

Returns On success return 1
On failure return 0
Description Copy from STDIN to named file.
Includes xilmfs.h

int mfs_file_copy (char *from_file, char *to_file)

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

120 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Additional Utilities

Additional Utilities
A 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 Customization
Memory 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 LIBRARY
parameter LIBRARY_NAME = xilmfs
parameter LIBRARY_VER = 1.00.a

EDK OS and Libraries Reference Guide www.xilinx.com 121

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 9: LibXil Memory File System (MFS)

parameter numbytes= 50000

parameter base_address = 0xffe00000
parameter init_type = MFSINIT_NEW
parameter need_utils = false
END

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.

122 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Chapter 10

LibXil Profile
This chapter describes the profiling library for embedded processors, libXil Profile. The
chapter contains the following sections:
x “Overview”
x “Features”
x “Profiling Model”
x “Customizing xilprofile”
x “Building Applications”
x “Generating GPROF Files”
x “XilProfile Code Description”
x “Limitations”

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

Features
LibXil Profile library has the following features:
x Provides Histogram (flat profile) and Call Graph information.
i Histogram: Shows how much time the program spent in each function and how
many times the function was called.
i Call Graph: Shows for each function, which functions called it, which other
functions it called and how many times.
x Profiling parameters are configurable - Sampling Frequency, Histogram Bin Size and
Timer to use.
x Memory location and size to store profiling is flexible and configurable based on
program requirements.

EDK OS and Libraries Reference Guide www.xilinx.com 123

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 10: LibXil Profile

Profiling Model
The 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 xilprofile
The xilprofile library can be customized for an application. Following is the list of
PARAMETERS for the library.

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 none The opb_timer instance name to use for
instance name 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.

Building Applications
The 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.
x char *memstart - Points to start of memory location.
x char *memend - Points to end of memory location.

124 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Generating GPROF Files

Application Memory Requirements

The 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 Files

XMD 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

EDK OS and Libraries Reference Guide www.xilinx.com 125

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 10: LibXil Profile

** 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 Description

XilProfile source code is located at $XILINX_EDK/sw/lib/sw_services/xilprofile_v1_00_a
directory.
Some of the important functions are:
x _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.
x 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.
x 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.
x memstart, memend - determines the profile memory used.
x binsize - determines the Histogram BIN size used.
x sample_freq_hz - determines the Sampling Frequency used.
x profile_no_funcptr - determines the method used for call graph.

126 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Limitations

x _gmonparam - Data stored during profiling and information about the data. Refer
profile.h file for more details on this structure.

Limitations
The profiled program (text section) should exist as contiguous memory.

EDK OS and Libraries Reference Guide www.xilinx.com 127

UG114 (v3.0) June 22, 2004 1-800-255-7778
 R

Chapter 10: LibXil Profile

128 www.xilinx.com EDK OS and Libraries Reference Guide

1-800-255-7778 UG114 (v3.0) June 22, 2004
 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:
x “Overview”
x “PowerPC System”
x “MicroBlaze System”
x “Setting Up lwIP in EDK”
x “Designing an lwIP Application”
x “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 :
x IP (Internet Protocol) including packet forwarding on multiple interfaces
x ICMP (Internet Control Message Protocl)
x UDP (User Datagram Protocol)
x TCP (Transmission Control Protocol)
x .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.

EDK OS and Libraries Reference Guide www.xilinx.com 129

UG114 (v3.0) June 22, 2004 1-800-255-7778 Embedded Development Kit
 R

Chapter 11: lwIP Library

PLB OPB

SDRAM 10/100
DSPLB MEMC Ethernet

ISPLB
INT

BRAM 32 KB UART
MEMC BRAM 16450
PPC405
Non-Crit PLB2OPB
INTC BRIDGE

GPIO

UG114_11_01_051404

Figure 11-1: PowerPC System Design for lwIP-Based Echo Server

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.

OPB

SDRAM
MEMC
MICROBLAZE ILMB DLMB
10/100
ILMB Ethernet
DLMB
IOPB MDM
DOPB

Interrupt GPIO

UART
BRAM 32K BRAM 16550
MEMC BRAM MEMC
OPB
TIMER
UG114_11_02_051404

Figure 11-2: MicroBlaze System Design for lwIP-Based Echo Server

130 www.xilinx.com EDK OS and Libraries Reference Guide

Embedded Development Kit 1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Memory Management

Memory Management
There 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:

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.

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 LIBRARY
PARAMETER LIBRARY_NAME = lwip
PARAMETER LIBRARY_VER = 1.00.a
PARAMETER EMAC_INSTANCES =
((my_opb_ethernet,0x00,0x00,0x00,0x00,0x22,0x38))

EDK OS and Libraries Reference Guide www.xilinx.com 131

UG114 (v3.0) June 22, 2004 1-800-255-7778 Embedded Development Kit
 R

Chapter 11: lwIP Library

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 LIBRARY
PARAMETER LIBRARY_NAME = lwip
PARAMETER LIBRARY_VER = 1.00.a
PARAMETER 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.

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

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.

132 www.xilinx.com EDK OS and Libraries Reference Guide

Embedded Development Kit 1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Designing an lwIP Application

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.

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 *sent() tcp_sent()
by Remote Host
TCP Data Received *recv() tcp_recv()

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)

EDK OS and Libraries Reference Guide www.xilinx.com 133

UG114 (v3.0) June 22, 2004 1-800-255-7778 Embedded Development Kit
 R

Chapter 11: lwIP Library

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.

134 www.xilinx.com EDK OS and Libraries Reference Guide

Embedded Development Kit 1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Example lwIP Application

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 Application

The 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

EDK OS and Libraries Reference Guide www.xilinx.com 135

UG114 (v3.0) June 22, 2004 1-800-255-7778 Embedded Development Kit
 R

Chapter 11: lwIP Library

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

notice,

. * this list of conditions and the following disclaimer in the

documentation

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

136 www.xilinx.com EDK OS and Libraries Reference Guide

Embedded Development Kit 1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Example lwIP Application

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

OF

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

static u8_t my_timer = 0;

// External Global Variables

/* defined in lwip/src/core/tcp.c */
extern u32_t tcp_ticks;

EDK OS and Libraries Reference Guide www.xilinx.com 137

UG114 (v3.0) June 22, 2004 1-800-255-7778 Embedded Development Kit
 R

Chapter 11: lwIP Library

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

138 www.xilinx.com EDK OS and Libraries Reference Guide

Embedded Development Kit 1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Example lwIP Application

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

EDK OS and Libraries Reference Guide www.xilinx.com 139

UG114 (v3.0) June 22, 2004 1-800-255-7778 Embedded Development Kit
 R

Chapter 11: lwIP Library

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;

140 www.xilinx.com EDK OS and Libraries Reference Guide

Embedded Development Kit 1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Example lwIP Application

/*---------------------------------------------------------------*/

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

gateway
IP4_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 */

/*---------------------------------------------------------------*/

EDK OS and Libraries Reference Guide www.xilinx.com 141

UG114 (v3.0) June 22, 2004 1-800-255-7778 Embedded Development Kit
 R

Chapter 11: lwIP Library

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("

142 www.xilinx.com EDK OS and Libraries Reference Guide

Embedded Development Kit 1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Example lwIP Application

\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,

EDK OS and Libraries Reference Guide www.xilinx.com 143

UG114 (v3.0) June 22, 2004 1-800-255-7778 Embedded Development Kit
 R

Chapter 11: lwIP Library

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

notice,

. * this list of conditions and the following disclaimer in the

documentation

. * 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 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, WHETHER

IN

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

*
*/

144 www.xilinx.com EDK OS and Libraries Reference Guide

Embedded Development Kit 1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Example lwIP Application

#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 void
echo_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 void
close_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 void
send_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) {

EDK OS and Libraries Reference Guide www.xilinx.com 145

UG114 (v3.0) June 22, 2004 1-800-255-7778 Embedded Development Kit
 R

Chapter 11: lwIP Library

pbuf_chain(q, es->p);
es->p = q;
return;

}
tcp_recved(pcb, q->len);
pbuf_free(q);

} while(es->p != NULL);
}
/*------------------------------------------------------------------*/
static err_t
echo_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_t
echo_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_t
echo_recv(void *arg, struct tcp_pcb *pcb, struct pbuf *p, err_t err)
{

146 www.xilinx.com EDK OS and Libraries Reference Guide

Embedded Development Kit 1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Example lwIP Application

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_t
echo_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");

EDK OS and Libraries Reference Guide www.xilinx.com 147

UG114 (v3.0) June 22, 2004 1-800-255-7778 Embedded Development Kit
 R

Chapter 11: lwIP Library

return ERR_OK;
}
/*------------------------------------------------------------------*/
void
echo_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

148 www.xilinx.com EDK OS and Libraries Reference Guide

Embedded Development Kit 1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Example lwIP Application

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

EDK OS and Libraries Reference Guide www.xilinx.com 149

UG114 (v3.0) June 22, 2004 1-800-255-7778 Embedded Development Kit
 R

Chapter 11: lwIP Library

} > 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
/*

150 www.xilinx.com EDK OS and Libraries Reference Guide

Embedded Development Kit 1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Example lwIP Application

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

notice,

. * this list of conditions and the following disclaimer in the

documentation

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

EDK OS and Libraries Reference Guide www.xilinx.com 151

UG114 (v3.0) June 22, 2004 1-800-255-7778 Embedded Development Kit
 R

Chapter 11: lwIP Library

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

OF

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

static u8_t my_timer = 0;
static int waiting_for_timer = 1;

/* defined in lwip/src/core/tcp.c */
extern u32_t tcp_ticks;

152 www.xilinx.com EDK OS and Libraries Reference Guide

Embedded Development Kit 1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Example lwIP Application

/* 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();
}

EDK OS and Libraries Reference Guide www.xilinx.com 153

UG114 (v3.0) June 22, 2004 1-800-255-7778 Embedded Development Kit
 R

Chapter 11: lwIP Library

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");

154 www.xilinx.com EDK OS and Libraries Reference Guide

Embedded Development Kit 1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Example lwIP Application

/*------------------------------------------------------------------*/
/* 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 ticks
need 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);

/*----------------------------------------------------------------

EDK OS and Libraries Reference Guide www.xilinx.com 155

UG114 (v3.0) June 22, 2004 1-800-255-7778 Embedded Development Kit
 R

Chapter 11: lwIP Library

* 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");

156 www.xilinx.com EDK OS and Libraries Reference Guide

Embedded Development Kit 1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Example lwIP Application

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

gateway
IP4_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");

EDK OS and Libraries Reference Guide www.xilinx.com 157

UG114 (v3.0) June 22, 2004 1-800-255-7778 Embedded Development Kit
 R

Chapter 11: lwIP Library

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

158 www.xilinx.com EDK OS and Libraries Reference Guide

Embedded Development Kit 1-800-255-7778 UG114 (v3.0) June 22, 2004
 R

Example lwIP Application

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

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.

EDK OS and Libraries Reference Guide www.xilinx.com 159

UG114 (v3.0) June 22, 2004 1-800-255-7778 Embedded Development Kit
 R

Chapter 11: lwIP Library

160 www.xilinx.com EDK OS and Libraries Reference Guide

Embedded Development Kit 1-800-255-7778 UG114 (v3.0) June 22, 2004