MMAC
Software Group
API – UARTs
EMMA2 Software User’s Manual
Contents
1 Introduction .....................................................................................................................................2
1.1 Overview...............................................................................................................................2
1.2 Description............................................................................................................................4
2 Architecture .....................................................................................................................................6
2.1 Return Codes .......................................................................................................................6
2.2 Includes ................................................................................................................................7
2.3 Initialisation ...........................................................................................................................7
2.4 Configuration ........................................................................................................................7
2.5 Type Definitions ....................................................................................................................8
2.6 Sample Code ......................................................................................................................11
3 Function Prototypes ......................................................................................................................12
MMAC_UART_Initialise......................................................................................................12
MMAC_UART_Open ..........................................................................................................13
MMAC_UART_Close..........................................................................................................15
MMAC_UART_Read ..........................................................................................................17
MMAC_UART_Write ..........................................................................................................19
MMAC_UART_Cntrl ...........................................................................................................21
4 Revision History ............................................................................................................................23
Book No: n/a (shared document) Doc No: MMAC0158, Issue: 1.0
© NEC Electronics Corporation 2003, 2004 Date: 2004-02-16
The information is this document is subject to change without notice – it is the reader’s responsibility to check that this is the current version.
This document includes company confidential information. It should only be released to third parties under a Non-Disclosure Agreement.
1 Introduction
1.1 Overview
This document defines the API for the MMAC UART driver.
The API is defined in terms of a read/write/open/close/control interface. Parameter passing is
facilitated through I/O parameter blocks. Functions are passed a pointer to a function dependent
structure that contains input and output parameters.
The MMAC UART driver supports the UART channels provided by the Emma hardware –
MMAC_UART_0, MMAC_UART_1, MMAC_UART_2 and MMAC_UART_3.
MMAC_UART_0 and MMAC_UART_1
The first two channels are “fast” UARTs. They support hardware flow control using DTR/DSR or
RTS/CTS and can work in either buffer mode or DMA mode (the default mode being buffer mode).
Flow control is enabled by using the MMAC_UART_Cntrl( ) function with an MMAC_UART_
SET_PARAMS operation (see example later). If enabled, the type of flow control used will be
determined by whether or not MMAC_UART_DTR_FLOW_CNTRL has been defined in your build in
api.h. If this is defined in your build then DTR/DSR flow control is used. Otherwise, RTS/CTS flow
control is used. Note that the RTS line is shared with the 1284 module on Emma2/2+ devices and
some conflict might arise if both modules are used together. The flow control can either be handled
automatically by the driver or manually by the user, through the same function call.
The mode of operation (buffer or DMA) is set in api.h through the definition of
MMAC_UART_DMA_MODE. If MMAC_UART_DMA_MODE is defined then data is transferred
to/from the UART using DMA, into a user-supplied buffer. Otherwise, data is read from the UART
into an internal buffer where it is stored until the data is copied into a user-supplied buffer.
Note that in buffer mode when flow control becomes active up to 16 bytes of data may be sent before
the transmission stops. This is due to the data already in the UART FIFO being automatically sent.
This can be reduced by decreasing the size of the UART TX FIFO, by setting the define
UART_TX_FIFO_LEN in uart.c. In DMA mode this problem does not exist.
The DMA mode should be used when the intended application is to transfer large blocks of data
synchronously. In this mode, the MMAC_UART_Read( ) function always blocks waiting on data
for MMAC_UART_0 and MMAC_UART_1. Full-duplex mode is not available in DMA mode.
MMAC_UART_2 and MMAC_UART_3
The other two channels are functionally equivalent, but they have no hardware flow control and do
not support DMA. Any requested operation that is supported by MMAC_UART_0 and
MMAC_UART_1, and is not supported by the other two channels, results in an error being reported.
Operation Notes
The pins for the UART interfaces are normally shared with other peripheral devices care should be
taken to ensure that the required UART interface has full access to the Emma hardware.
The MMAC_UART_Initialise( ) function is used to perform any non channel specific initialisation
of the UART driver and must be called before any of the other functions.
The MMAC_UART_Open( ) function is used to initialise the UART driver for a given channel and
must be called before any functions, other than MMAC_UART_Initialise( ), for that channel.
The MMAC_UART_Write( ) function is used to send data via the UART hardware, for a given
channel. This function blocks until all data is transferred to a buffer (for later transmission under
interrupt), a hardware error occurs or a timeout occurs. The timeout can be changed using the
2 / 23
MMAC_UART_Cntrl( ) function. When an error occurs extra error information is available using
the MMAC_UART_Cntrl( ) function, with the operation MMAC_UART_GET_ERROR.
The MMAC_UART_Read( ) function is used to read data from the UART driver, for a given
channel. The read operation can be blocking or non-blocking, this can be changed using the
MMAC_UART_Cntrl( ) function. When an error occurs extra error information is available using
the MMAC_UART_Cntrl( ) function , with the operation MMAC_UART_GET_ERROR.
The MMAC_UART_Cntrl( ) function is used to configure, retrieve configuration information and to
retrieve error information from the driver for a given channel. This is done by specifying a control
function operation and passing configuration information to the control function, or retrieving
information from the control function.
The function MMAC_UART_Close( ) is called to disable the UART driver for a given channel and
return system resources.
MMAC_UART_2 and MMAC_UART_3 cannot be guaranteed to work without loss of data at speeds
above 19200 baud.
The default settings for each UART channel are taken from those defined in the file
include/mmac/config/api.h (see later).
These settings are read/modified using the MMAC_UART_Cntrl( ) function with the operation
MMAC_UART_GET_PARAMS or MMAC_UART_SET_PARAMS.
Note a readTimeout value of 0 means the driver is in non-blocking mode.
A write timeout of 0 means that a MMAC_UART_Write( ) performs no blocking so data waiting to
be sent may not be. A sensible write timeout should be based on the amount of data being sent and the
communications protocol being used.
A read or write timeout of MMAC_RTOS_MAX_TIMEOUT means that the operation blocks
indefinitely until all the requested data is received or transmitted.
3 / 23
1.2 Description
The following diagram defines the context of the MMAC UART driver in terms of the UART driver
and the direction of data flow from that driver, using the given functions:
MMAC_UART_Cntrl
MMAC_UART_Initialise
MMAC_UART_Read
MMAC UART
MMAC_UART_Open Driver
MMAC_UART_Write
MMAC_UART_Close
UART_ISR
The MMAC UART driver is used to send/receive data to/from the UART channels supported by the
EMMA hardware.
The driver implements the following functions:
• MMAC_UART_Initialise: perform any non channel specific initialisation of the UART driver
• MMAC_UART_Open: initialise and allocate system resources for a UART channel
• MMAC_UART_Close: deactivate a UART channel and return system resources
• MMAC_UART_Read: read data from the MMAC UART driver
• MMAC_UART_Write: write data to the MMAC UART driver
• MMAC_UART_Cntrl: configure/query the MMAC UART driver
• UART_ISR: transfer data between MMAC UART driver buffers and the EMMA2 hardware
The driver uses semaphores to facilitate task synchronisation. The following semaphores are defined
for each channel:
writeAccess
Allow only one write operation at a time
readAccess
Allow only one read operation at a time
writeCompleted
Block task until a write operation is complete
readDataAvailable
Block until all requested read data is available
4 / 23
The UART driver is asynchronous.
Received data for a given channel is buffered in an internal receive buffer by the UART_ISR function.
The MMAC_UART_Read( ) function is used to read data from the internal receive buffer. The
receive buffer acts a temporary storage to prevent the UART FIFO overflowing and remove the need
for constant use of flow control. The read can be non-blocking, i.e. read as much data as is available
from the internal buffer up to the requested number of bytes, or can be blocking, i.e. wait until the
requested number of bytes are available in the internal receive buffer before returning the data.
Transmitted data is copied from the buffer passed into the MMAC_UART_Write( ) function to the
EMMA hardware. The calling task is blocked on the writeCompleted semaphore until either all data
is sent, a timeout of the semaphore occurs, or an error is detected by the driver ISR. No intermediate
buffer is required for the transmit operation.
The buffer management structures and semaphore are encapsulated in a UART control block structure,
one per channel. The unique device number is used to identify the control structure for a given
channel.
An MMAC_UART_Initialise( ) function is provided for completeness, to make the UART driver
consistent with other API drivers. This is intended to perform any general initialisation of the UART
driver. However since all initialisation is channel specific and performed in the
MMAC_UART_Open( ) function, this routine is only a stub.
The MMAC UART driver for a given channel is initialised with a call to MMAC_UART_Open( ).
Access and control semaphores for the channel are created, using the MMAC_RTOS_
CreateSemaphore service, which returns a pointer to a semaphore identifier. An ISR is installed for
a given channel and the vector enabled. The default set-up for a UART channel is set and the
hardware configured. The RX and error handling interrupts are enabled for the given channel. The
channel is then flagged as initialised.
The MMAC_UART_Close( ) function deactivates any interrupts that have been enabled for the
channel and deletes the access and control semaphores for the given channel. The ISR is removed and
the vector disabled. The channel is then flagged as uninitialised.
When a UART channel has been enabled, the UART_ISR buffers any incoming data in a receive
buffer for the given channel. The size of this buffer is defined at compile time, with a default of 1K
Bytes. The MMAC_UART_Read( ) function is used to asynchronously read data from the receive
buffer into a buffer passed to the function. Up to the requested number of bytes are copied from the
receive buffer into the iopb buffer for the given channel. The function may block until enough data is
available to service the request (blocking mode) or may return immediately with what ever data is
already available, up to the requested number of bytes (non-blocking mode).
A MMAC_UART_Write( ) operation copies a block of data into the transmit buffer/FIFO for the
given channel. The transmit interrupt for the given UART is then initialised. When the transmit
buffer/FIFO empty interrupt is received, the next block of data is copied into the buffer/FIFO by the
ISR. This is repeated until there is no more data to copy. The driver blocks on the writeCompleted
semaphore, blocking the calling task while the transfer is in progress. When all data is sent an error or
a write timeout occurs and the semaphore is released, allowing the blocked task to run.
The MMAC_UART_Cntrl( ) operation is used to set the baud rate, number of data bits etc. for a
given channel and is used to query and set the configuration. The current error status for a given
channel can also be read.
5 / 23
2 Architecture
2.1 Return Codes
The meanings of the various return codes are as follows:
Result Code Description
MMAC_UART_OK A UART operation has successfully completed.
MMAC_UART_FAIL A UART operation has not completed. A call to
MMAC_UART_Cntrl can be made to determine the
specific error.
MMAC_UART_ALREADY_OPEN The UART driver has already been initialised.
MMAC_UART_NOT_OPEN The UART driver has not been initialised.
MMAC_UART_TIMEOUT The UART read/write operation has timed out, the
operation has aborted.
MMAC_UART_INVALID_PARAM A parameter passed is invalid, it is out of range or a
NULL pointer has been passed.
MMAC_UART_INVALID_DEVICE The device number is not within the range defined in
MMAC_UART_DEV_NUM.
MMAC_UART_NOT_SUPPORTED An operation has been requested which is not supported
by a given UART.
MMAC_UART_NOT_INITIALISED An attempt to use UART driver before
MMAC_UART_Initialise has been called.
MMAC_UART_ALREADY_INITIALISED Attempt to call MMAC_UART_Initialise more than once
MMAC_UART_HARDWARE_NOT_ The UART port requested has not been enabled by the
ENABLED hardware strap settings
6 / 23
2.2 Includes
In order to use this API, the following header files must be included in order:
#include “mmac/types.h”
#include “mmac/rtos.h”
#include “mmac/mmac_config.h”
#include “mmac/uart.h”
2.3 Initialisation
Prior to using any functions of the XXX API, the following functions must be called:
MMAC_RTOS_Initialise( ) – in all cases
MMAC_DMA_Initialise( ) – if DMA mode is to be used
2.4 Configuration
A number of configurable options, in the form of ‘#define’s are given in the UART section of the
api.h source file marked by the comment:
/************************************************************/
/* */
/* MMAC UART SETUP */
/* */
/************************************************************/
These options are:
Define Default Meaning
MMAC_UART_RX_BUFF_LEN 1024 In buffer mode, the read input
buffer length.
MMAC_UART_DEFAULT_ MMAC_UART_BR_19200 Baud rate of 19200 baud.
BAUD_RATE
MMAC_UART_DEFAULT_ MMAC_UART_STOP_1 1 stop bit.
STOP_BITS
MMAC_UART_DEFAULT_ MMAC_UART_DATA_8 8 data bits.
DATA_BITS
MMAC_UART_DEFAULT_ MMAC_UART_PARITY_ No parity.
PARITY NONE
MMAC_UART_DEFAULT_ MMAC_UART_FLOW_ Flow control off.
FLOW OFF
MMAC_UART_DEFAULT_ MMAC_RTOS_MAX_ Length of time a task is blocked
WRITE_TIMEOUT TIMEOUT until all the data is sent.
MMAC_UART_DEFAULT_ 0 Length of time a task is blocked
READ_TIMEOUT until a read request is fulfilled.
7 / 23
Define Default Meaning
MMAC_UART_FLOW_ MMAC_UART_RX_BUFF_ The level at which flow control is
CONTROL_ON_LEVEL LEN-18 activated when the receive buffer is
almost full.
MMAC_UART_FLOW_ (MMAC_UART_RX_BUFF_ The level at which flow control is
CONTROL_OFF_LEVEL LEN*10) / 100 de-activated when the receive
buffer is almost empty.
MMAC_UART_ACCESS_ MMAC_RTOS_MAX_ The length of time a task is blocked
CONTROL_WAIT_TIME TIMEOUT until is gains access to the UART
device.
MMAC_UART_DTR_FLOW_ (defined) If this is defined then RTS/DTR is
CONTROL used for flow control.
2.5 Type Definitions
Result Codes
The following result codes are defined for the UART device. The result code value 0 is reserved for
indication of a successful operation.
typedef enum
{
MMAC_UART_OK,
MMAC_UART_FAIL,
MMAC_UART_ALREADY_OPEN,
MMAC_UART_NOT_OPEN,
MMAC_UART_TIMEOUT,
MMAC_UART_INVALID_PARAM,
MMAC_UART_INVALID_DEVICE,
MMAC_UART_NOT_SUPPORTED,
MMAC_UART_NOT_INITIALISED,
MMAC_UART_ALREADY_INITIALISED,
MMAC_UART_HARDWARE_NOT_ENABLED
} MMAC_UART_RESULT_CODE;
Device Numbers
The MMAC UART driver has four channels, each of which has a unique device number.
typedef enum
{
MMAC_UART_0,
MMAC_UART_1,
MMAC_UART_2,
MMAC_UART_3
} MMAC_UART_DEV_NUM;
8 / 23
MMAC_UART_Open
The MMAC UART driver open operation requires the following IOPB.
typedef struct
{
MMAC_UART_DEV_NUM deviceNumber;
} MMAC_UART_OPEN_IOPB;
MMAC_UART_Close
The MMAC UART driver close operation requires the following IOPB.
typedef struct
{
MMAC_UART_DEV_NUM deviceNumber;
} MMAC_UART_CLOSE_IOPB;
MMAC_UART_Read
The MMAC UART driver read operation requires the following IOPB.
typedef struct
{
MMAC_UART_DEV_NUM deviceNumber;
UI8 *data;
UI16 length;
} MMAC_UART_READ_IOPB;
MMAC_UART_Write
The MMAC UART driver write operation requires the following IOPB.
typedef struct
{
MMAC_UART_DEV_NUM deviceNumber;
UI8 *data;
UI16 length;
} MMAC_UART_WRITE_IOPB;
MMAC_UART_Cntrl
The MMAC UART driver control operation requires the following definitions.
typedef enum
{
MMAC_UART_RESET,
MMAC_UART_GET_PARAMS,
MMAC_UART_SET_PARAMS,
MMAC_UART_GET_ERROR
} MMAC_UART_OPERATION;
9 / 23
typedef enum
{
MMAC_UART_BR_300,
MMAC_UART_BR_600,
MMAC_UART_BR_1200,
MMAC_UART_BR_2400,
MMAC_UART_BR_4800,
MMAC_UART_BR_9600,
MMAC_UART_BR_19200,
MMAC_UART_BR_38400,
MMAC_UART_BR_57600,
MMAC_UART_BR_115200,
MMAC_UART_BR_144000
} MMAC_UART_BAUDRATE;
typedef enum
{
MMAC_UART_STOP_1,
MMAC_UART_STOP_1_5,
MMAC_UART_STOP_2
} MMAC_UART_STOPBITS;
typedef enum
{
MMAC_UART_DATA_5,
MMAC_UART_DATA_6,
MMAC_UART_DATA_7,
MMAC_UART_DATA_8
} MMAC_UART_DATABITS;
typedef enum
{
MMAC_UART_PARITY_NONE,
MMAC_UART_PARITY_EVEN,
MMAC_UART_PARITY_ODD
} MMAC_UART_PARITY;
typedef enum
{
MMAC_UART_FLOW_OFF,
MMAC_UART_FLOW_ON,
MMAC_UART_FLOW_MANUAL
} MMAC_UART_FLOW;
typedef enum
{
MMAC_UART_DTR_RTS_LOW,
MMAC_UART_DTR_RTS_HIGH
} MMAC_UART_DTR_RTS_STATE;
typedef struct
{
MMAC_UART_BAUDRATE baudrate;
MMAC_UART_STOPBITS stopbits;
MMAC_UART_DATABITS databits;
MMAC_UART_PARITY parity;
MMAC_UART_FLOW flowControl;
MMAC_UART_DTR_RTS_STATE DTR_RTS_State;
UI32 writeTimeout;
UI32 readTimeout;
} MMAC_UART_PARAMS;
10 / 23
typedef enum
{
MMAC_UART_NO_ERROR = 0x00,
MMAC_UART_PARITY_ERROR = 0x01,
MMAC_UART_OVERRUN_ERROR = 0x02,
MMAC_UART_FRAMING_ERROR = 0x04,
MMAC_UART_BREAK_ERROR = 0x08,
MMAC_UART_HW_ERROR = 0x10,
MMAC_UART_BUFFER_OVERFLOW = 0x20
} MMAC_UART_HARDWARE_ERROR;
typedef struct
{
MMAC_UART_DEV_NUM deviceNumber;
MMAC_UART_OPERATION operation;
MMAC_UART_PARAMS params;
MMAC_UART_HARDWARE_ERROR error;
} MMAC_UART_CNTRL_IOPB;
2.6 Sample Code
Refer to the individual function descriptions for sample code.
11 / 23
3 Function Prototypes
MMAC_UART_Initialise
Function Prototype
MMAC_UART_RESULT_CODE MMAC_UART_Initialise (void);
Inputs
None.
Outputs
None.
Event Notification
N/A
Returns
MMAC_UART_OK
MMAC_UART_FAIL
Description
This function performs all general, non channel specific, initialisation required by the UART driver.
This function returns MMAC_UART_FAIL if initialisation fails. Otherwise it returns
MMAC_UART_OK.
See Also
MMAC_UART_Open( )
MMAC_UART_Close( )
MMAC_UART_Read( )
MMAC_UART_Write( )
MMAC_UART_Cntrl( )
Sample Code
{
MMAC_RTOS_Initialise();
If (MMAC_UART_Initialise() != MMAC_UART_OK)
{
return(NOT_OK);
}
}
12 / 23
MMAC_UART_Open
Function Prototype
MMAC_UART_RESULT_CODE MMAC_UART_Open (MMAC_UART_OPEN_IOPB *iopb);
Inputs
iopb
This points to an MMAC_UART_OPEN_IOPB structure. This structure is used to pass in the
following parameter:
deviceNumber
The device number for the UART open.
Outputs
None.
Event Notification
N/A
Returns
MMAC_UART_OK
MMAC_UART_FAIL
MMAC_UART_INVALID_DEVICE
MMAC_UART_INVALID_PARAM
MMAC_UART_ALREADY_OPEN
Description
This function initialises the given UART channel, ready for reading and writing, and allocates system
resources. The given UART channel is configured with the default channel settings.
This function returns:
MMAC_UART_INVALID_PARAM if iopb is NULL,
MMAC_UART_INVALID_DEVICE if deviceNumber is not a valid channel,
MMAC_UART_ALREADY_OPEN if the channel has been previously initialised,
MMAC_UART_FAIL if the allocation of system resources for this channel fails.
Otherwise it returns MMAC_UART_OK.
See Also
MMAC_UART_Initialise( )
MMAC_UART_Close( )
MMAC_UART_Read( )
MMAC_UART_Write( )
MMAC_UART_Cntrl( )
13 / 23
Sample Code
{
MMAC_UART_OPEN_IOPB openIOPB;
MMAC_RTOS_Initialise();
If (MMAC_UART_Initialise() != MMAC_UART_OK)
{
return (NOT_OK);
}
/* Select the device to open */
[Link] = deviceNumber;
/* Open the UART */
MMAC_UART_Open(&openIOPB);
}
14 / 23
MMAC_UART_Close
Function Prototype
MMAC_UART_RESULT_CODE MMAC_UART_Close (MMAC_UART_CLOSE_IOPB *iopb);
Inputs
iopb
This points to an MMAC_UART_CLOSE_IOPB structure. This structure is used to pass in the
following parameter:
deviceNumber
The device number for the UART close.
Outputs
None.
Event Notification
N/A
Returns
MMAC_UART_OK
MMAC_UART_INVALID_DEVICE
MMAC_UART_INVALID_PARAM
MMAC_UART_NOT_OPEN
Description
The given UART channel is disabled and any system resources previously allocated are returned.
This function returns:
MMAC_UART_INVALID_PARAM if iopb is NULL,
MMAC_UART_INVALID_DEVICE if deviceNumber is not a valid channel,
MMAC_UART_NOT_OPEN if the channel has not been previously initialised.
Otherwise it returns MMAC_UART_OK.
See Also
MMAC_UART_Initialise( )
MMAC_UART_Open( )
MMAC_UART_Read( )
MMAC_UART_Write( )
MMAC_UART_Cntrl( )
15 / 23
Sample Code
{
MMAC_UART_CLOSE_IOPB closeIOPB;
MMAC_UART_OPEN_IOPB openIOPB;
MMAC_RTOS_Initialise();
If (MMAC_UART_Initialise() != MMAC_UART_OK)
{
return (NOT_OK);
}
/* Select the device to open */
[Link] = deviceNumber;
/* Open the UART */
MMAC_UART_Open(&openIOPB);
/* Select the device to close */
[Link] = deviceNumber;
/* Close the UART */
MMAC_UART_Close(&closeIOPB);
16 / 23
MMAC_UART_Read
Function Prototype
MMAC_UART_RESULT_CODE MMAC_UART_Read (MMAC_UART_READ_IOPB *iopb);
Inputs
iopb
This points to an MMAC_UART_READ_IOPB structure. This structure is used to pass in the
following parameters:
deviceNumber
The device number for the UART read.
length
Length of the data to read.
data
A pointer to a buffer for storing read data.
Outputs
iopb
This points to an MMAC_UART_READ_IOPB structure. This structure is used to pass out the
following parameters:
length
The number of bytes stored in buffer.
data
Data is passed back in the buffer pointed to by this pointer.
Event Notification
N/A
Returns
MMAC_UART_OK
MMAC_UART_FAIL
MMAC_UART_TIMEOUT
MMAC_UART_INVALID_DEVICE
MMAC_UART_INVALID_PARAM
MMAC_UART_NOT_OPEN
Description
In non-blocking mode, this function reads up to length bytes from the given UART channel. If less
than length bytes are available then only that number are returned.
In blocking mode this function blocks the calling task for a given length of time, or until the
requested number of bytes is available. If a timeout occurs before the requested number of bytes is
available, then all the data available is returned.
This function is non-blocking by default but can be made blocking using the MMAC_UART_
Cntrl( ) function with the MMAC_UART_SET_PARAMS operation.
If the driver is built for DMA mode the driver is always blocking and a buffer large enough to
accommodate the requested number of bytes should be passed in.
If an error code is returned by the function more information about the error can be retrieved from the
driver, using the MMAC_UART_Cntrl( ) function, with the MMAC_UART_GET_ERROR operation.
17 / 23
This function returns:
MMAC_UART_INVALID_PARAM if iopb or iopb->data is NULL,
MMAC_UART_INVALID_DEVICE if deviceNumber is not a valid channel,
MMAC_UART_NOT_OPEN if the channel has not been previously initialised,
MMAC_UART_FAIL if the read fails, and
MMAC_UART_TIMEOUT if the read times out.
Otherwise it returns MMAC_UART_OK.
See Also
MMAC_UART_Initialise( )
MMAC_UART_Close( )
MMAC_UART_Open( )
MMAC_UART_Write( )
MMAC_UART_Cntrl( )
Sample Code
{
MMAC_UART_OPEN_IOPB openIOPB;
MMAC_UART_CNTRL_IOPB cntrlIOPB;
MMAC_UART_READ_IOPB readIOPB;
MMAC_RTOS_Initialise();
If (MMAC_UART_Initialise() != MMAC_UART_OK)
{
return (NOT_OK);
}
/* Open the uart port */
[Link] = MMAC_UART_0;
MMAC_UART_Open(&openIOPB);
[Link] = MMAC_UART_0;
[Link] = MMAC_UART_GET_PARAMS;
MMAC_UART_Cntrl(&cntrlIOPB);
[Link] = MMAC_UART_SET_PARAMS;
[Link] = MMAC_UART_BR_9600;
[Link] = 50;
MMAC_UART_Cntrl(&cntrlIOPB);
[Link] = 10;
[Link] = &buffer;
[Link] = MMAC_UART_0;
MMAC_UART_Read(&readIOPB);
}
18 / 23
MMAC_UART_Write
Function Prototype
MMAC_UART_RESULT_CODE MMAC_UART_Write (MMAC_UART_WRITE_IOPB *iopb);
Inputs
iopb
This points to an MMAC_UART_WRITE_IOPB structure. This structure is used to pass the
following parameters:
deviceNumber
The device number for the UART write.
length
Length of the data to write.
data
A pointer to a buffer of data.
Outputs
iopb
This points to an MMAC_UART_WRITE_IOPB structure. This structure is used to pass out
the following parameter:
length
The actual number of bytes written.
Event Notification
N/A
Returns
MMAC_UART_OK
MMAC_UART_FAIL
MMAC_UART_TIMEOUT
MMAC_UART_INVALID_DEVICE
MMAC_UART_INVALID_PARAM
MMAC_UART_NOT_OPEN
Description
This function writes the data passed to it via the iopb to the given UART channel. This function
blocks until all data is sent, unless an unrecoverable error is encountered, or the time required to write
the data reaches the timeout value for the write operation. The initial write timeout value is
MMAC_RTOS_MAX_TIMEOUT, meaning that the operation blocks indefinitely.
If an error code is returned by this function more information about the error can be retrieved from
the driver using the MMAC_UART_Cntrl( ) function with the MMAC_UART_GET_ERROR
operation.
This function returns:
MMAC_UART_INVALID_PARAM if iopb or iopb->data is NULL,
MMAC_UART_INVALID_DEVICE if deviceNumber is not a valid channel,
MMAC_UART_NOT_OPEN if the channel has not been previously initialised,
MMAC_UART_FAIL if the write fails, and
MMAC_UART_TIMEOUT if the write times out.
19 / 23
Otherwise it returns MMAC_UART_OK.
See Also
MMAC_UART_Initialise( )
MMAC_UART_Close( )
MMAC_UART_Read( )
MMAC_UART_Open( )
MMAC_UART_Cntrl( )
Sample Code
{
MMAC_UART_OPEN_IOPB openIOPB;
MMAC_UART_CNTRL_IOPB cntrlIOPB;
MMAC_UART_WRITE_IOPB writeIOPB;
MMAC_RTOS_Initialise();
If (MMAC_UART_Initialise() != MMAC_UART_OK)
{
return (NOT_OK);
}
/* Open the uart port */
[Link] = MMAC_UART_0;
MMAC_UART_Open(&openIOPB);
[Link] = MMAC_UART_0;
[Link] = MMAC_UART_GET_PARAMS;
MMAC_UART_Cntrl(&cntrlIOPB);
[Link] = MMAC_UART_SET_PARAMS;
[Link] = MMAC_UART_BR_9600;
[Link] = 50;
MMAC_UART_Cntrl(&cntrlIOPB);
[Link] = 10;
[Link] = &buffer;
[Link] = MMAC_UART_0;
MMAC_UART_Write(&writeIOPB);
}
20 / 23
MMAC_UART_Cntrl
Function Prototype
MMAC_UART_RESULT_CODE MMAC_UART_Cntrl (MMAC_UART_CNTRL_IOPB *iopb);
Inputs
iopb
This points to an MMAC_UART_CNTRL_IOPB structure. This structure is used to pass the
following parameters:
deviceNumber
The device number for the UART cntrl.
operation
An operation for the control function to perform. Allowable operations are:
MMAC_UART_RESET Reset the UART hardware and driver.
MMAC_UART_GET_PARAMS Return current configuration for UART in
iopb, in [Link].
MMAC_UART_SET_PARAMS Set current configuration of UART from
iopb, in [Link].
MMAC_UART_GET_ERROR Return and clear the last internal UART
error, in [Link].
params
A structure containing the new port configuration for the UART, valid when
operation is MMAC_UART_SET_PARAMS.
Outputs
iopb
This points to an MMAC_UART_CNTRL_IOPB structure. This structure is used to pass out
the following parameters:
params
A structure containing the current port configuration for the UART, valid when
operation is MMAC_GET_PARAMS.
error
The last recorded set of errors for the UART on a bit-wise basis, see
MMAC_UART_HARDWARE_ERROR. Valid when operation is
MMAC_GET_ERROR.
Event Notification
N/A
Returns
MMAC_UART_OK
MMAC_UART_FAIL
MMAC_UART_INVALID_DEVICE
MMAC_UART_INVALID_PARAM
MMAC_UART_NOT_OPEN
MMAC_UART_NOT_SUPPORTED
21 / 23
Description
This function is used to change or query the given UART channel configuration.
This function returns:
MMAC_UART_INVALID_PARAM if iopb or iopb->data is NULL,
MMAC_UART_INVALID_DEVICE if deviceNumber is not a valid channel,
MMAC_UART_NOT_OPEN if the channel has not been previously initialised,
MMAC_UART_FAIL if access to the device fails, and
MMAC_UART_NOT_SUPPORTED if the requested operation is not supported.
Otherwise it returns MMAC_UART_OK.
See Also
MMAC_UART_Initialise( )
MMAC_UART_Open( )
MMAC_UART_Close( )
MMAC_UART_Read( )
MMAC_UART_Write( )
Sample Code
To set the baud rate and blocking mode of a given UART channel the following code segment would
be executed:
{
MMAC_UART_OPEN_IOPB openIOPB;
MMAC_UART_CNTRL_IOPB cntrlIOPB;
MMAC_RTOS_Initialise();
If (MMAC_UART_Initialise() != MMAC_UART_OK)
{
return (NOT_OK);
}
/* Open the uart port */
[Link] = MMAC_UART_0;
MMAC_UART_Open(&openIOPB);
[Link] = MMAC_UART_0;
[Link] = MMAC_UART_GET_PARAMS;
MMAC_UART_Cntrl(&cntrlIOPB);
[Link] = MMAC_UART_SET_PARAMS;
[Link] = MMAC_UART_BR_9600;
[Link] = 50;
MMAC_UART_Cntrl(&cntrlIOPB);
}
This sets the baud rate of MMAC_UART_0 to 9600 baud and enables blocking mode, allowing
MMAC_UART_Read( ) to block for up to 50ms.
22 / 23
4 Revision History
Title: API – UARTs
Ref: API_UART.doc
Date Issue Details of change Ref.
2002-09-13 0.01 First Draft. M-PL
2002-09-18 0.02 Updated for standardisation. M-PL
2002-09-20 0.03 Proofreading edits. M-DS
2003-01-02 0.04 Doc layout reorganised. M-RJI
2003-01-16 0.05 Minor formatting edits. M-RJI
2003-04-29 0.06 Minor edits – to remove highlighted text M-JSA
2003-07-02 0.07 Document numbers added. Function descriptions re-organised. M-RJI
2004-02-16 1.0 This document made common across all EMMA2 devices – replaces M-RJI
previous API_UART doc.
23 / 23