cell maker guide

5/21/2018 Cell Maker Guide

1/22

Maker Communications, Inc.73 Mount Wayte Avenue

Framingham, Massachusetts 01702M

CellMaker Host Interface

User Guide

Beta

Order Number: 100479-00


2/22

Copyright 1998 by Maker Communications, Inc. All rights reserved.

Printed in the United States of America.

The information in this document is believed to be correct, however, the information can change without notice. Maker Communications, Inc. disclaims any responsibility for

any consequences resulting from the use of the information contained in this document.

The hardware, software, and the related documentation is provided with RESTRICTED RIGHTS. Use, duplication, or disclosure by the U.S. Government is subject to

restrictions as set forth in subparagraph (c)(1) (ii ) of The Rights in Technical Data and Computer Program Product clause at DFARS 252.227-7013 or subparagraphs (c)(1) and

(2) of the Commercial Computer Software-Restricted Rights at 48 CFR 52.227-19, as applicable.

Contractor/manufacturer is:

Maker Communications, Inc.73 Mount Wayte Avenue

Framingham, MA 01702

CellMaker is a registered trademark or Maker Communications, Inc.

BridgeMaker, AccessMaker, CodeMaker, LinkMaker, and SWAN, are t rademarks of Maker Communications, Inc.

All other trademarks are owned by their respective companies.

This manual supersedes and obsoletes all previous version of the document from Maker Communications publications.


3/22

Contents

CellMaker Host Interface (CMHI)

cmhiInit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

cmhiLoadImage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

cmhiOpen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

cmhiHasMXT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

cmhiClose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

cmhiCloseBoard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

cmhiReset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

cmhiResetBoard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

cmhiCOMMOUTStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

cmhiCOMMOUTWait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

cmhiCOMMOUTRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

cmhiCOMMINStatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

cmhiCOMMINWait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

cmhiCOMMINWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

cmhiCommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

cmhiICSWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

cmhiICSRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

cmhiCopyOut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

cmhiCopyIn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

cmhiResetTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

cmhiTimeHasElapsed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14


4/22

iv CellMaker Host Interface User Guide

cmhiCSRRead . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

cmhiCSRWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

cmhiWaitCSRSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

cmhiInitForDownLoad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

cmhiWaitTargetTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

stop_csim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17


5/22


This preliminary document describes the CellMaker host interface (CMHI) libraries and functions.

The Cellmaker Host Interface (CMHI) library provides an application interface whereby user applications in the Windows

NT or the UNIX environment can interface and control a target MXT3010 system:

CellMaker Simulator (CSIM)

MXT3025 Evaluation Board

MXT3016 Evaluation Board

The CMHI library includes functions whereby a user application can control and communicate with shared memory, the

MXT3010 ATM cell processor, and with the MXT3020 TDM coprocessor. The user can open one or more of the logical unit

on the target system and proceed to control their behavior for developing, testing, and debugging.

User applicationsCellMaker Applications

Diagnostics and Debuggers

CMHI

PLI drivers

UNIX Shared Memory

CSIM

Drivers

Physical Shared Memory

MXT3010 SWAN Processor


6/22

2 CellMaker Host Interface User Guide


cmhiInit

void cmhiInit (void)

This function initializes all data structures that are maintained by CMHI during the execution of the user

application. Each user application must call this function once before opening or performing operations on any

devices.

cmhiLoadImage

Boolean cmhiLoadImage (CMHI *ck, char *filename, int bootstyle)

This function places the diagnostic into the boot loader state. Loads a specified data file into shared memory.

Transfers control to the loaded code.

Input Parameters Description

CMHI *ck The handle of a logical unit. See cmhiOpen on page 3for more

information.

char *filename Specifies the hex or extended hex file to load.

int bootstyle This specifies the intended load source:

0 = COMMIN load

1 = Shared memory load

Return Value

Boolean If a 1, the load was successful

If a 0, the load failed


7/22

CellMaker Host Interface User Guide 3

cmhiOpen

The user application must call this function once for each logical unit to be controlled or to be communicated with.

It must be the first function called for that logical unit.


int boardno A zero-based index that specifies which board to target.

int deviceIndex Specifies the logical unit that is to be opened:

0 = the receive Port1 memory and the MXT3010.

1 = the transmit Port1 memory and the MXT3010 (MXT3016 only).

2 = the receive Port2 memory (MXT3016 only).

3 = the transmit Port2 memory (MXT3016 only).

4 = the entirety of the Port2 memory on the MXT3016 board (not

supported on CSIM).

Output Parameters

void **shBase A pointer to the base of the shared memory space for the logical unit. The

shared memory base pointer that is returned must be used as the base for

all memory reads and writes to the memory space for this device.

uint32 *size The number of bytes contained in the shared memory space of the logical

unit.

Return Value

CMHI * A CMHI device handle. The device handle that is returned from this

function must be supplied on all further function calls that operate on this

device.

CMHI* cmhiOpen (int boardno, int deviceIndex, void **shBase, uint32 *size)


8/22



cmhiHasMXT

Boolean cmhiHasMXT (int boardno, int deviceIndex)

The programmer can issue this call to determine if a given logical unit is associated with a physical MXT3010.

Currently the logical devices 0 and 1 (MXT3016 only) will return TRUE and the others will return FALSE. This is

because only Port1 MemMakers have the capability to offer the I/O register accesses that constitute host

communication with an MXT3010.

cmhiClose

void cmhiClose (CMHI *ck)

This function is used to close a logical unit that was initially opened using the cmhiOpen function described on

page 3. The action of this function is to internally mark the logical unit as not in use. If the logical unit being

closed is the last one open on the board, the CMHI library closes the device driver that is associated with the device.


int boardno An index specifying one of several boards.

int deviceIndex An index specifying one of several logical units.

Return Value

Boolean TRUE if the logical unit is associated with an MXT3010.

FALSE if not.



information.


9/22


cmhiCloseBoard

void cmhiCloseBoard (int boardno)

The programmer can call this function instead of issuing separate cmhiClose calls for each logical unit on a board.The action of this function is to issue repeated calls to the cmhiClose function, one call for each open logical unit.

cmhiReset

void cmhiReset (CMHI *ck)

The programmer can call this function in order to reset a given MXT3010. This call can be issued only against

logical units that have an associated MXT3010.


int boardno The index of the board to be closed.



information.


10/22



cmhiResetBoard

void cmhiResetBoard (int boardno)

This function resets all of the MemMakers and MXT3010s on the target board.

cmhiCOMMOUTStatus

Boolean cmhiCOMMOUTStatus (CMHI *ck)

This function returns TRUE if the COMMOUT register has data, or FALSE if otherwise.


int boardno The index of the board that is to be reset.



information.

Return

Boolean TRUE if the COMMOUT_RDY bit in the CSR is set. FALSE if it is not.


11/22


cmhiCOMMOUTWait

Boolean cmhiCOMMOUTWait (CMHI *ck, int32 maxWait)

The user calls this function to wait for data available at COMMOUT. It will wait up to maxWait seconds before itreturns.

cmhiCOMMOUTRead

uint32 cmhiCOMMOUTRead (CMHI *ck, int32 maxWait)

The user calls this function to read the COMMOUT register of an MXT3010.



information.

int32 maxWait The number of seconds to wait before returning a timeout,

except:

0= do not wait

-1= wait forever

Return Value

Boolean TRUE if data is available.

FALSE if a time-out occurred.



information.


except:

0 = do not wait

-1 = wait forever

Return Value

uint32 If 0, a time-out has occurred, or the COMMOUT value is

zero (0).

If otherwise, the contents of the COMMOUT register.


12/22



cmhiCOMMINStatus

Boolean cmhiCOMMINStatus (CMHI *ck)

The user calls this function to determine whether it is permissible to write to the COMMIN register. If the return

value is true, COMMIN can be written.

cmhiCOMMINWait

Boolean cmhiCOMMINWait (CMHI *ck, int32 maxWait)

The user calls this function to wait until COMMIN is has available data, or until time-out.



information.

Return Value

Boolean If TRUE, the COMMIN_BSY bit in the CSR is clear

If FALSE, otherwise


CMHI *ck The handle of a logical unit. See cmhiOpen on page 3for moreinformation.


except:

0=do not wait

-1=wait forever

Return Value

Boolean TRUE if COMMIN is empty and available for writing

FALSE if a time-out occurred and COMMIN is still full


13/22


cmhiCOMMINWrite

Boolean cmhiCOMMINWrite (CMHI *ck, uint32 value,int32 maxWait)

The user calls this function to write data to the COMMIN register within a given time or else to return a time-outindication.



information.

uint32 value The value is the data to write to COMMIN.


except:

0=do not wait

-1=wait forever

Return Value

Boolean TRUE if COMMIN was written.

FALSE if a time-out occurred and COMMIN is still full

from a previous write.


14/22



cmhiCommand

The user calls this function to write COMMIN and wait for a response in COMMOUT. The function waits for the

COMMIN_BSY bit to be clear before writing to COMMIN and waits for the COMMOUT_RDY bit to be set before

reading COMMOUT.


CMHI *ck

The handle of a logical unit. See cmhiOpen on page 3for more

information.

uint32 command The data that is to be written to COMMIN


except:

0 = do not wait

-1 = wait forever

Output Parameters

uint32 *output The data that was read from COMMOUT

Return Value

Boolean TRUE if COMMIN was written and COMMOUT was read

FALSE if a timeout occurred

Boolean cmhiCommand (CMHI *ck, uint32 command, uint32*output, int32 maxWait)


15/22


cmhiICSWrite

void cmhiICSWrite (CMHI *ck, int bit, uint32 value)

The user calls this function to set or clear an ICS bit in the MXT3010 control/status register on platforms thatsupport them.

cmhiICSRead

int cmhiICSRead (CMHI *ck, int bit)

The user calls this function to find out the value of a given bit in the MXT3010 control/status register.



information.

int bit This value is the bit position to write. The least significant bit

(LSB) is bit 0.

uint32 value Valid values are 1 or 0.



information.

int bit The position to read. The least significant bit (LSB) is bit 0.

Return Value

int 1 if the bit is be set

0 if the bit is clear


16/22



cmhiCopyOut

void cmhiCopyOut (CMHI *ck, uint32 dest, void *source, uint32 count)

The user calls this routine to write data out to Port1 or Port2 shared memory. This is simply a block copy in

software. The data is written in such a way as to prevent the host from attempting to write in burst mode on targets

that do not support burst mode.

This function only transfers an even number of bytes. If an odd number of bytes is specified, the count is rounded

up to make it even.



information.

uint32 dest An offset into the shared memory of the device

void *source A pointer to the data to write

uint32 count The number of bytes to write


17/22


cmhiCopyIn

void cmhiCopyIn (CMHI *ck, void *dest, uint32 source, uint32 count )

The user calls this routine to read data in from shared memory. This is simply a block copy in software.

This function only transfers an even number of bytes. If an odd number of bytes is specified, the count is rounded

up to make it even.



information.

void *dest A pointer to the area to receive the data.

uint32 source An offset into the shared memory of the device

uint32 count The number of bytes to be read


18/22



cmhiResetTime

void cmhiResetTime (time_t *spot)

The user calls this function to capture the value of the current time. The result can then be used be passed to the

function cmhiTimeHasElapsed to determine when a given period of time has elapsed.

cmhiTimeHasElapsed

Boolean cmhiTimeHasElapsed (time_t *then, int value)

The user calls this function to determine whether a specified period of time has elapsed since a specified timer was

set. The specified timer can be set before you call this function by using cmhiResetTime function.

Output Parameters Description

time_t *spot A pointer to a timer block to receive the time


time_t *then This points to a previously set timer.

int value The number of seconds to test for.

Return Value

Boolean TRUE if the time has elapsed

FALSE if it has not


19/22


cmhiCSRRead

uint32 cmhiCSRRead (CMHI *ck)

The user calls this function in order to read the contents of the specified device status register.

cmhiCSRWrite

void cmhiCSRWrite (CMHI *ck, int32 value)

The user calls this function to write the specified value to the command/status register of a device.



information.

Return Value

uint32 The contents of the CSR.



information.

int32 value The data that is to be written to the command/status register.


20/22



cmhiWaitCSRSet

Boolean cmhiWaitCSRSet (CMHI *ck, uint32 bit, int32 maxWait)

This function waits for a specific bit to be set in the status register of a device.

cmhiInitForDownLoad

Boolean cmhiInitForDownLoad (CMHI *ck)

This function must be called before the cmhiLoadImage function. It assures that the firmware is synchronized into

a WAIT_FOR_HOST state. See cmhiLoadImage on page 2for more information.



information.

uint32 bit The number of the bit that is to be monitored. The least

significant bit (LSB) is zero (0).


except: 0= do not wait

-1 = wait forever

Return Value

Boolean FALSE if the wait timed out

TRUE if the bit was set



information.

Return Value

Boolean If TRUE, synchronization was successful and the target is

ready to download.

If FALSE, a synchronization error occurred.


21/22


cmhiWaitTargetTime

void cmhiWaitTargetTime (int cn, int size)

This function inserts a wait to ensure a complete direct memory access (DMA) function by the firmware. This is aCSIM specific function.

stop_csim

void stop_csim (int cn)

This CSIM specific function terminates CSIM and returns control to the UNIX prompt.


int cn CSIM number

0 = transmit

1 = received

int size The number of bytes that the firmware is transferring by the

DMA function.


int cn CSIM number 0 = transmit

1 = received


22/22



cell maker guide

Documents