User’s Manual

EMMA2 API

ATA

Contents

1 Introduction ....................................................................................................................... 2
1.1 Example of ATA API Use...................................................................................... 4
2 Function Prototypes .......................................................................................................... 6
MMAC_ATA_Initialise ...................................................................................................6
MMAC_ATA_Open .......................................................................................................7
MMAC_ATA_DMARead ...............................................................................................8
MMAC_ATA_DMAWrite..............................................................................................10
MMAC_ATA_PIORead ...............................................................................................12
MMAC_ATA_PIOWrite ...............................................................................................13
MMAC_ATA_QueryDevice .........................................................................................14
MMAC_ATA_InstallCriticalErrorHandler.....................................................................17
MMAC_ATA_NonDataCommand ...............................................................................18
MMAC_ATA_Close.....................................................................................................20
3 Data Structures ............................................................................................................... 21
4 Revision History .............................................................................................................. 24

Book No: S16753EE1V0UM00 Doc No: MMAC0003, Issue: 1.2

© NEC Electronics Corporation 2002, 2005 Publication Date: 2005-07-14
The information is this document is subject to change without notice – it is
the reader’s responsibility to check that this is the latest available version.

This document includes company confidential information. It should only be

released to third parties under a Non-Disclosure Agreemant.
1 Introduction
This document specifies the EMMA2 (Enhanced Multimedia Architecture) ATA (AT Attachment) API
(Application Programmers Interface).
The ATA driver allows access to an ATA device (e.g. a disk drive) via the EMMA 2 ATA/IDE interface.
A device can be addressed only using logical block addressing (LBA). The driver works in a synchronous
fashion, with a callback function mechanism being provided for notification of critical errors and transfer
completion. If the ATA bus is already in use, calling tasks will be blocked until the ATA interface
becomes available for use. The value assigned to MMAC_ATA_SEMAPHORE_TIMEOUT in the file
mmac_config.h determines the maximum period a task will be blocked in this manner.
This driver is designed for use with devices supporting ATA/ATAPI-5.
Up to two devices may be connected to the ATA bus, although one device may be addressed at any given
time.
The ATA API provides the following functions:
Function Name Description
MMAC_ATA_Initialise Used to allocate the resources necessary to use the ATA
subsystem.
MMAC_ATA_Open Used to create a connection to a device.
MMAC_ATA_DMARead Used to read blocks of data from a device via DMA.
MMAC_ATA_DMAWrite Used to write blocks of data to a device via DMA.
MMAC_ATA_PIORead Used to read blocks of data from a device via PIO.
MMAC_ATA_PIOWrite Used to write blocks of data to a device via PIO.
MMAC_ATA_QueryDevice Used to obtain details about an attached device.
MMAC_ATA_ Used to register a function that will be called in the event
InstallCriticalErrorHandler of a critical error.
MMAC_ATA_NonDataCommand Used to perform non-data commands on an attached
device.
MMAC_ATA_Close Used to terminate a connection to a device.

2
Result Codes
The meanings of the various result codes returned by the API are described in the following table:
Result Code Description
MMAC_ATA_OK An ATA operation has successfully completed.
MMAC_ATA_FAIL An ATA operation has not completed successfully
MMAC_ATA_NOT_INITIALISED The ATA subsystem has not yet been initialised
MMAC_ATA_ALREADY_INITIALISED The ATA subsystem has already been initialised
MMAC_ATA_NOT_OPEN The specified drive has not been opened
MMAC_ATA_ALREADY_OPEN The specified drive has already been opened
MMAC_ATA_SEMAPHORE_UNAVAILABLE The driver timed-out while attempting to acquire the
access semaphore.
MMAC_ATA_INVALID_PARAM The driver has been passed an invalid parameter.
MMAC_ATA_NO_RESPONSE_FROM_DEVICE The driver was unable to communicate with the
specified device.

Includes
In order to use this API, the following header files must be included, in the following order:
#include “mmac/types.h”
#include “mmac/rtos.h”
#include “mmac/mmac_config.h”
#include “mmac/dma.h”
#include “mmac/ata.h”

Initialisations
Prior to using any functions of the ATA API, the following functions must be called:
MMAC_RTOS_Initialise()
MMAC_DMA_Initialise()

API Configuration
A number of configurable options, in the form of “#define”s are defined in the ATA section of the
mmac_config.h source file clearly marked by the comment:

/****************************************************************/
/* */
/* MMAC ATA SETUP */
/* */
/****************************************************************/

These options are:

Define Default Meaning
MMAC_ATA_SEMAPHORE_ MMAC_RTOS_ Number of system ticks the subsystem will
TIMEOUT MAX_TIMEOUT wait when attempting to acquire the drive
access semaphore.
MMAC_ATA_HISR_STACK_ 1024 Specifies the size allocated to the ATA
SIZE HISR stack (in bytes)

3
Define Default Meaning
MMAC_ATA_ 0x20000 Limits the size of individual DMA transfers
MAXBYTESPERTRANSFER to and from the ATA device. Larger
transfers will be performed by the API as a
series of smaller transfers of this size, plus
any residual data. This restriction is
imposed by the ATA device
MMAC_ATA_PARAMETER_ MMAC_NO Determines whether or not the ATA API will
CHECKING perform any checks on the parameters
passed when called.
This should be set to MMAC_YES during
application development and testing, but
may be set to MMAC_NO to improve
performance once application code has
been verified.

1.1 Example of ATA API Use

/* Declaration of our callback function */

void exampleCallback ( UI32 errorRegValue );
/* Declare some identifiers… */
MMAC_ATA_RW_IOPB iopb;
MMAC_ATA_RESULT_CODE result;

/* Initialise ATA API subsystem */

result = MMAC_ATA_Initialise();

if (result == MMAC_ATA_OK)
{
/* Open the Master IDE drive... */
result = MMAC_ATA_Open(MMAC_ATA_MASTER_DRIVE);

if (result == MMAC_ATA_OK)
{
/* Set-up a callback function in case of critical errors */
MMAC_ATA_InstallCriticalErrorHandler(exampleCallback);

[Link] = MMAC_ATA_MASTER_DRIVE;
[Link] = 0x26dfc0;
[Link] = &dataReadToBuffer;
[Link] = 256;

/* Read data from the Master disk into the buffer

(using DMA)... */
/* This call will be blocked if the device is currently busy */
/* ‘transferCompletionCallback’ will be called when the data */
/* has been transferred – code can wait on a flag being set */
/* in this function, as shown below... */
transferDone = MMAC_FALSE;
MMAC_ATA_DMARead(&iopb, transferCompletionCallback);

/* Wait for transfer to have finished (‘transferDone’ is set */

/* to MMAC_TRUE in the function transferCompletionCallback() )*/
while( transferDone == MMAC_FALSE )
{
/* Code must ‘sleep’ to allow the low-priority ATA */
/* callback task to perform the callback */

4
 MMAC_RTOS_Sleep(MMAC_RTOS_MSEC_TO_TICKS(10));
}

/* Open the Slave IDE drive... */

result = MMAC_ATA_Open(MMAC_ATA_SLAVE_DRIVE);

if (result == MMAC_ATA_OK)
{
[Link] = MMAC_ATA_SLAVE_DRIVE;
[Link] = &dataWriteFromBuffer;
[Link] = 120;
[Link] = 0x14dfa0;
/* Write data from another buffer to the Slave disk (PIO)... */
/* This call will be blocked if the device is currently busy */
MMAC_ATA_PIOWrite(&iopb);

/* Close the Slave drive… */

MMAC_ATA_Close(MMAC_ATA_SLAVE_DRIVE);
}
/* Close the Master drive… */
MMAC_ATA_Close(MMAC_ATA_MASTER_DRIVE);
}
}

5
2 Function Prototypes

MMAC_ATA_Initialise

Function Prototype
MMAC_ATA_RESULT_CODE MMAC_ATA_Initialise (void);

Inputs
None

Outputs
None

Event Notification
N/A

Return Codes
MMAC_ATA_OK
MMAC_ATA_FAIL
MMAC_ATA_ALREADY_INITIALISED

Description
This function is used to initialise the ATA subsystem. It allocates the resources necessary to manage the
ATA subsystem (installing the interrupt handlers, access semaphore, etc). It must be called prior to calling
any other function in the ATA API.
If the subsystem has already been initialised, the function returns MMAC_ATA_ALREADY_INITIALISED
without performing any actions.
If the necessary resources cannot be allocated, the function will return MMAC_ATA_FAIL without
initialising the subsystem.
The function will allow seven seconds for any attached drives to spin-up to their operating speed (the
calling task will be blocked for this time). It will then return the code MMAC_ATA_OK.

See Also
None

Sample Code
< tba >

6
MMAC_ATA_Open

Function Prototype
MMAC_ATA_RESULT_CODE MMAC_ATA_Open (
MMAC_ATA_DRIVE_ID drive
);

Inputs
drive The drive to open – MMAC_ATA_MASTER_DRIVE or
MMAC_ATA_SLAVE_DRIVE.

Outputs
None

Event Notification
N/A

Return Codes
MMAC_ATA_OK
MMAC_ATA_NOT_INITIALISED
MMAC_ATA_ALREADY_OPEN
MMAC_ATA_SEMAPHORE_UNAVAILABLE
MMAC_ATA_NO_RESPONSE_FROM_DEVICE

Description
This function is used to open a connection to an ATA device. The device will be addressed using Logical
Block Addressing (LBA). If present, details are obtained about the features supported by the attached
device, and it is initialised to use the fastest mode it supports for transferring data.
If the subsystem has not yet been initialised, the function returns MMAC_ATA_NOT_INITIALISED
without performing any further action.
If the ATA interface is currently in use, the function will block while waiting to obtain the access semapho
re. Should it time out (the timeout period is determined by the value MMAC_ATA_SEMAPHORE_TIMEOUT)
the function will return MMAC_ATA_SEMAPHORE_UNAVAILABLE without opening the drive.
If the device specified in the drive parameter has already been opened, the function returns
MMAC_ATA_ALREADY_OPEN.
The function will perform a soft reset on the ATA interface. It will then obtain information about the
device, by performing an IDENTIFY DEVICE command. If the specified device fails to respond, the
function returns MMAC_ATA_NO_RESPONSE_FROM_DEVICE without performing any further actions
If a connection is made with the specified device, the function will initialise the device to use the fastest
data transfer mode it can support when performing subsequent PIO and DMA transfers. The code
MMAC_ATA_OK is then returned.

See Also
MMAC_ATA_Close

Sample Code
< tba >

7
MMAC_ATA_DMARead

Function Prototype
MMAC_ATA_RESULT_CODE MMAC_ATA_DMARead (
MMAC_ATA_RW_IOPB *iopb,
MMAC_ATA_CALLBACK callback
);

Inputs
Iopb Pointer to a read/write parameter block
drive Drive to read from
startLba Starting logical block address
bytes Number of bytes to read
buffer Address of buffer into which data read from the disk will be placed
callback Function to be called when the DMA transfer has completed. This function will
also be called in addition to the installed Critical Error Handler should a transfer
fail.
The value NULL may be passed to specify that no callback is required.

Outputs
Data read from the disk is placed in buffer.

Event Notification
N/A

Return Codes
MMAC_ATA_OK
MMAC_ATA_FAIL
MMAC_ATA_NOT_OPEN
MMAC_ATA_SEMAPHORE_UNAVAILABLE

Description
This function is used to transfer data from the specified drive to SDRAM, via DMA/UDMA.
The value specified in bytes must be a multiple of the number of bytes per sector (defined by the value
MMAC_ATA_BYTESPERSECTOR). This means that a whole number of sectors will be always
transferred. If MMAC_ATA_PARAMETER_CHECKING is enabled, the function will return
MMAC_ATA_FAIL if the value of iopb->bytes is not a multiple of the number of bytes per sector.
If iopb is NULL, MMAC_ATA_FAIL is returned.
If the specified drive has not been opened MMAC_ATA_NOT_OPEN is returned.
If the address specified in iopb->buffer is not aligned to the multiple of bytes required by the DMAC, the
function returns MMAC_ATA_FAIL without performing any further action.
If the subsystem is unable to acquire the drive access semaphore within the time specified by
MMAC_ATA_SEMAPHORE_TIMEOUT (because the drive is currently in use), then
MMAC_ATA_SEMAPHORE_UNAVAILABLE is returned.
If the drive specified does not support DMA/UDMA data transfers, MMAC_ATA_FAIL is returned.
If there is a problem commencing the read operation, MMAC_ATA_FAIL is returned.
Otherwise data is transferred from the drive to the user buffer. The function is non-blocking, and will
return immediately with the code MMAC_ATA_OK.

8
Once the transfer is complete, the callback function specified in the callback parameter will be called.
Should the transfer fail, the driver will call the installed Critical Error Handler installed (see function
MMAC_ATA_InstallCriticalErrorHandler()), and also the callback function specified in the callback
parameter. The value in the ATA error register will be passed to both callbacks. The application can then
choose whether or not to re-issue the failed command.

See Also
MMAC_ATA_DMAWrite
MMAC_ATA_PIORead
MMAC_ATA_PIOWrite

Sample Code
< tba >

9
MMAC_ATA_DMAWrite

Function Prototype
MMAC_ATA_RESULT_CODE MMAC_ATA_DMAWrite (
MMAC_ATA_RW_IOPB *iopb,
MMAC_ATA_CALLBACK callback
);

Inputs
Iopb Pointer to a read/write parameter block
drive Drive to write to
startLba Starting logical block address
bytes Number of bytes to write
buffer Address of buffer from which data is to be written to the disk
callback Function to be called when the DMA transfer has completed. This function will
also be called in addition to the installed Critical Error Handler should a transfer
fail.
The value NULL may be passed to specify that no callback is required.

Outputs
None

Event Notification
N/A

Return Codes
MMAC_ATA_OK
MMAC_ATA_FAIL
MMAC_ATA_NOT_OPEN
MMAC_ATA_SEMAPHORE_UNAVAILABLE

Description
This function is used to transfer data from SDRAM to the specified drive, via DMA/UDMA.
The value specified in bytes must be a multiple of the number of bytes per sector (defined by the value
MMAC_ATA_BYTESPERSECTOR). This means that a whole number of sectors will be always
transferred. If MMAC_ATA_PARAMETER_CHECKING is enabled, the function will return
MMAC_ATA_FAIL if the value of iopb->bytes is not a multiple of the number of bytes per sector.
If iopb is NULL, MMAC_ATA_FAIL is returned.
If the specified drive has not been opened MMAC_ATA_NOT_OPEN is returned.
If the address specified in iopb->buffer is not aligned to the multiple of bytes required by the DMAC, the
function returns MMAC_ATA_FAIL without performing any further action.
If the subsystem is unable to acquire the drive access semaphore within the time specified by
MMAC_ATA_SEMAPHORE_TIMEOUT (because the drive is currently in use), then MMAC_ATA_
SEMAPHORE_UNAVAILABLE is returned.
If the drive specified does not support DMA/UDMA data transfers, MMAC_ATA_FAIL is returned.
If there is a problem commencing the write operation MMAC_ATA_FAIL is returned.
Otherwise data is transferred from the user buffer to the drive. The function is non-blocking, and will
return immediately with the code MMAC_ATA_OK.

10
Once the transfer is complete, the callback function specified in the callback parameter will be called.
Should the transfer fail, the driver will call the installed Critical Error Handler installed (see function
MMAC_ATA_InstallCriticalErrorHandler()), and also the callback function specified in the callback
parameter. The value in the ATA error register will be passed to both callbacks. The application can then
choose whether or not to re-issue the failed command.

See Also
MMAC_ATA_DMARead
MMAC_ATA_PIOWrite
MMAC_ATA_PIORead

Sample Code
< tba >

11
MMAC_ATA_PIORead

Function Prototype
MMAC_ATA_RESULT_CODE MMAC_ATA_PIORead (MMAC_ATA_RW_IOPB *iopb);

Inputs
Iopb Pointer to a read/write parameter block
drive Drive to read from
startLba Starting logical block address
bytes Number of bytes to read
buffer Address of buffer into which data read from the disk will be placed

Outputs
Data read from the disk is placed in buffer

Event Notification
N/A

Return Codes
MMAC_ATA_OK
MMAC_ATA_FAIL
MMAC_ATA_NOT_OPEN
MMAC_ATA_SEMAPHORE_UNAVAILABLE

Description
This function is used to transfer data from the specified drive to SDRAM, via PIO.
If iopb is NULL, MMAC_ATA_FAIL is returned.
If the specified drive has not been opened MMAC_ATA_NOT_OPEN is returned.
If the subsystem is unable to acquire the drive access semaphore within the time specified by
MMAC_ATA_SEMAPHORE_TIMEOUT (because the drive is currently in use), then MMAC_ATA_
SEMAPHORE_UNAVAILABLE is returned.
If there is a problem performing the read operation, MMAC_ATA_FAIL is returned.
Otherwise data is transferred from the drive to the user buffer via PIO. The function is blocking, and will
return with the code MMAC_ATA_OK once the data has been transferred.

See Also
MMAC_ATA_PIOWrite
MMAC_ATA_DMARead
MMAC_ATA_DMAWrite

Sample Code
< tba >

12
MMAC_ATA_PIOWrite

Function Prototype
MMAC_ATA_RESULT_CODE MMAC_ATA_PIOWrite (MMAC_ATA_RW_IOPB *iopb);

Inputs
Iopb Pointer to a read/write parameter block
drive Drive to write to
startLba Starting logical block address
bytes Number of bytes to write
buffer Address of buffer from which data is to be written to the disk

Outputs
None

Event Notification
N/A

Return Codes
MMAC_ATA_OK
MMAC_ATA_FAIL
MMAC_ATA_NOT_OPEN
MMAC_ATA_SEMAPHORE_UNAVAILABLE

Description
This function is used to transfer data from SDRAM to the specified drive, via PIO.
If iopb is NULL, MMAC_ATA_FAIL is returned.
If the specified drive has not been opened MMAC_ATA_NOT_OPEN is returned.
If the subsystem is unable to acquire the drive access semaphore within the time specified by
MMAC_ATA_SEMAPHORE_TIMEOUT (because the drive is currently in use), then
MMAC_ATA_SEMAPHORE_UNAVAILABLE is returned.
If there is a problem performing the write operation MMAC_ATA_FAIL is returned.
Otherwise data is transferred from the drive to the user buffer via PIO. The function is blocking, and will
return with the code MMAC_ATA_OK once the data has been transferred.

See Also
MMAC_ATA_PIORead
MMAC_ATA_DMAWrite
MMAC_ATA_DMARead

Sample Code
< tba >

13
MMAC_ATA_QueryDevice

Function Prototype
MMAC_ATA_RESULT_CODE MMAC_ATA_QueryDevice (
MMAC_ATA_DRIVE_ID drive,
MMAC_ATA_DRIVE_INFO *driveInfo
);

Inputs
Drive The drive to be queried – either MMAC_ATA_MASTER_DRIVE or
MMAC_ATA_SLAVE_DRIVE.

Outputs
DriveInfo A pointer to a structure in which details about the attached device will be
returned. The details correspond to those returned from performing an ATA
IDENTIFY DEVICE command.
Media A UI16 value that contains the value of word 0 of
the IDENTIFY COMMAND response.
defaultLogicalCylinders A UI16 value that contains the value of word 1 of
the IDENTIFY COMMAND response.
defaultLogicalHeads A UI16 value that contains the value of word 3 of
the IDENTIFY COMMAND response.
defaultLogicalSectors A UI16 value that contains the value of word 6 of
the IDENTIFY COMMAND response.
serialNo A 20 character serial number read from the device.
It is constructed from the value of words 10 to 19 of the IDENTIFY
COMMAND response.
firmwareVersion An 8 character firmware version number read
from the device. It is constructed from the value of words 23 to 26 of the
IDENTIFY COMMAND response.
modelName A 40 character model name read from the device. It
is constructed from the value of words 27 to 46 of the IDENTIFY COMMAND
response.
multiSector A UI16 value that contains the value of word 47 of
the IDENTIFY COMMAND response.
iordySupport A UI16 value that contains the value of word 49 of
the IDENTIFY COMMAND response.
capabilities A UI16 value that contains the value of word 50 of
the IDENTIFY COMMAND response.
extendedWords A UI16 value that contains the value of word 53 of
the IDENTIFY COMMAND response.
CurrentCylinders A UI16 value that contains the value of word 54 of
the IDENTIFY COMMAND response.
currentHeads A UI16 value that contains the value of word 55 of
the IDENTIFY COMMAND response.
currentSectorsPerTrack A UI16 value that contains the value of word 56 of
the IDENTIFY COMMAND response.

14
 chsCurrentCapacity A UI32 value that contains the value of words 57
and 58 of the IDENTIFY COMMAND response.
multiSectorValid A UI16 value that contains the value of word 59 of
the IDENTIFY COMMAND response.
lbaCurrentCapacity A UI64 value that contains the value of words 60
and 61 or 100:103 for large drives of the IDENTIFY COMMAND response.
multiWordDma A UI16 value that contains the value of word 63 of
the IDENTIFY COMMAND response.
advancedPio A UI16 value that contains the value of word 64 of
the IDENTIFY COMMAND response.
multiWordDmaMinTime A UI16 value that contains the value of word 65 of
the IDENTIFY COMMAND response.
multiWordDmaRecTime A UI16 value that contains the value of word 66 of
the IDENTIFY COMMAND response.
pioCycleNoFlowControl A UI16 value that contains the value of word 67 of
the IDENTIFY COMMAND response.
PioCycleWithFlowControl A UI16 value that contains the value of word 68 of
the IDENTIFY COMMAND response.
ataMajorVersion A UI16 value that contains the value of word 80 of
the IDENTIFY COMMAND response.
AtaMinorVersion A UI16 value that contains the value of word 81 of
the IDENTIFY COMMAND response.
commandSetsSupported[] An array of six UI16 values (indexed from 0 to 5)
that contains the value of words 82 to 87 of the IDENTIFY COMMAND
response.
udmaMode A UI16 value that contains the value of word 88 of
the IDENTIFY COMMAND response.

Event Notification
N/A

Return Codes
MMAC_ATA_OK
MMAC_ATA_NOT_OPEN
MMAC_ATA_INVALID_PARAM

Description
This function interrogates the device specified in the drive parameter, and returns information relating to it,
including the manufacturer, model, transfer modes supported and its capacity in the driveInfo parameter.
If the drive has not been opened MMAC_ATA_NOT_OPEN is returned.
If the value specified for the driveInfo parameter is NULL, MMAC_ATA_INVALID_PARAM is returned.
Otherwise, the function returns MMAC_ATA_OK.

See Also
None

Sample Code
< tba >

15
16
MMAC_ATA_InstallCriticalErrorHandler

Function Prototype
MMAC_ATA_RESULT_CODE MMAC_ATA_InstallCriticalErrorHandler (
MMAC_ATA_CRITICAL_ERROR_CALLBACK callback
);

Inputs
callback Pointer to a Critical Error Handler callback function

Outputs
None

Event Notification
N/A

Return Codes
MMAC_ATA_OK
MMAC_ATA_NOT_INITIALISED

Description
This function registers the specified callback function with the ATA subsystem, then returns
MMAC_ATA_OK. The function will be used as a Critical Error Handler.
Should an ATA command fail, the ATA driver’s Interrupt Service Routine will leave the ATA interface in
a re-usable state, and the Critical Error Handler will be called. The API will continue to block other
accesses to the ATA interface until returning from the Critical Error Handler
If the subsystem has not yet been initialised, the function returns MMAC_ATA_NOT_INITIALISED
without performing any further action.
The callback function will be called when a critical error condition occurs. The callback function must
have a single parameter of type MMAC_ATA_CRITICAL_ERROR_STRUCT, in which the details of the
failed command will be returned.

See Also
None

Sample Code
< tba >

17
MMAC_ATA_NonDataCommand

Function Prototype
MMAC_ATA_RESULT_CODE MMAC_ATA_NonDataCommand (
MMAC_ATA_COMMAND_STRUCTURE *iopb
);

Inputs
iopb Pointer to a structure containing the parameters for the non-data command:
drive The drive for which the specified command is intended
(MMAC_ATA_MASTER_DRIVE or MMAC_ATA_SLAVE_DRIVE)
lba The value to be loaded into the LBA registers. (24-bit value)
sectorCount The value to be loaded into the Sector Count register.
features The value to be placed in the Features register
command The value to be loaded into the Command register.

Outputs
None

Event Notification
N/A

Return Codes
MMAC_ATA_OK
MMAC_ATA_FAIL
MMAC_ATA_INVALID_PARAM
MMAC_ATA_NOT_OPEN
MMAC_ATA_SEMAPHORE_UNAVAILABLE

Description
This function is provided to allow applications to perform non-data transfer operations on a specified
device, for which no API function is already provided.
The function shall set-up the appropriate registers in the device.
If the command specified involves the transfer of data (via UDMA, DMA or PIO), the function shall
return MMAC_ATA_INVALID_PARAM without performing any actions. The API functions
MMAC_ATA_DMARead(), MMAC_ATA_DMAWrite(), MMAC_ATA_PIORead() and
MMAC_ATA_PIOWrite() should be used to transfer data to and from devices.
If drive has not been opened, MMAC_ATA_NOT_OPEN is returned.
If there is a problem setting up the registers, MMAC_ATA_FAIL is returned. Otherwise, the command is
executed on the specified device and MMAC_ATA_OK is returned. Should the command fail, the ATA
will invoke the installed Critical Error Handler (installed by calling
MMAC_ATA_InstallCriticalErrorHandler()).

See Also
MMAC_ATA_DMARead
MMAC_ATA_DMAWrite
MMAC_ATA_PIORead
MMAC_ATA_PIOWrite

Sample Code
< tba >

18
19
MMAC_ATA_Close

Function Prototype
MMAC_ATA_RESULT_CODE MMAC_ATA_Close (MMAC_ATA_DRIVE_ID drive);

Inputs
Drive Device to which the connection is to be closed

Outputs
None

Event Notification
N/A

Return Codes
MMAC_ATA_OK
MMAC_ATA_NOT_OPEN

Description
This function closes the connection to the specified device, then returns MMAC_ATA_OK.
If drive has not been opened, MMAC_ATA_NOT_OPEN is returned.

See Also
MMAC_ATA_Open

Sample Code
< tba >

20
3 Data Structures

Result Codes
The following result codes are defined for the AT Attachment driver. The result code zero is reserved for
indication of a successful operation.

typedef enum
{
MMAC_ATA_OK = 0,
MMAC_ATA_FAIL,
MMAC_ATA_NOT_INITIALISED,
MMAC_ATA_ALREADY_INITIALISED,
MMAC_ATA_NOT_OPEN,
MMAC_ATA_ALREADY_OPEN,
MMAC_ATA_SEMAPHORE_UNAVAILABLE,
MMAC_ATA_NO_RESPONSE_FROM_DEVICE,
MMAC_ATA_INVALID_PARAM
}MMAC_ATA_RESULT_CODE;

Drive Identifier

typedef enum
{
MMAC_ATA_MASTER_DRIVE = 0,
MMAC_ATA_SLAVE_DRIVE
}MMAC_ATA_DRIVE_ID;

Read and Write Parameter Block

The following type defines the parameter-passing block used for read and write operations.

typedef struct
{
MMAC_ATA_DRIVE_ID drive;
UI64 startLba;
UI64 bytes;
void *buffer;
}MMAC_ATA_RW_IOPB;

Non-data Command Structure

The following type defines the structure used to specify the parameters for a non-data command.

typedef struct
{
MMAC_ATA_DRIVE_ID drive;
UI32 lba;
UI16 sectorCount;
UI8 features
I8 command;
}MMAC_ATA_COMMAND_STRUCTURE;

21
Drive Information Structure
The following type is used to return information relating to an attached device.

typedef struct{
UI32 chsCurrentCapacity;
UI64 lbaCurrentCapacity;
UI16 media;
UI16 defaultLogicalCylinders;
UI16 defaultLogicalHeads;
UI16 defaultLogicalSectors;
UI16 multiSector;
UI16 iordySupport;
UI16 capabilities;
UI16 extendedWords;
UI16 currentCylinders;
UI16 currentHeads;
UI16 currentSectorsPerTrack;
UI16 multiSectorvalid;
UI16 multiWordDma;
UI16 advancedPio;
UI16 multiWordDmaMinTime;
UI16 multiWordDmaRecTime;
UI16 pioCycleNoFlowControl;
UI16 pioCycleWithFlowControl;
UI16 ataMajorVersion;
UI16 ataMinorVersion;
UI16 commandSetsSupport[6];
UI16 udmaMode;
UI8 serialNo[21];
UI8 firmwareVersion[9];
UI8 modelName[41];
} MMAC_ATA_DRIVE_INFO;

Critical Error Details Structure

The following type defines the structure used to provide details of a critical error/failed command.

typedef struct
{
I8 drive;
I18 command;
I32 error;
I32 lba;
I32 sectorCount;
}MMAC_ATA_CRITICAL_ERROR_STRUCT;

ATA Callback
An ATA callback function (to be called when a DMA transfer has completed) is defined as follows:

typedef void (*MMAC_ATA_CALLBACK)( UI32 errorRegValue );

ATA Critical Error Callback

An ATA callback function (to be called when a critical error occurs) is defined as follows:

typedef void (*MMAC_ATA_CRITICAL_ERROR_CALLBACK

(MMAC_ATA_CRITICAL_ERROR_STRUCT criticalErrorDetails);

22
Defines

#define MMAC_ATA_SERIAL_NUMBER_LENGTH (20)

#define MMAC_ATA_BYTESPERBLOCK (512)

23
4 Revision History
Title: API Specifiaction: ATA
Ref: API_ATA.doc

Date Doc API Details of change Ref.

Ver. Ver.
0.01 First Draft M-GM
0.02 Updated to reflect style and format of other API M-RV
documentation. Also, implemented further API functions.
0.03 Added blockingTime parameter to MMAC_HDD_Read(), M-RV
MMAC_HDD_Write, and MMAC_HDD_Erase(). Added list
of ‘mmac_config.h’ #defines for the subsystem.
0.04 Removed blockingTime parameter and made it a #define in M-RV
‘mmac_config.h’. Added semaphore access timeout.
Added return codes for each timeout condition to
MMAC_HDD_Read(), MMAC_HDD_Write() and
MMAC_HDD_Erase().
0.05 Added function MMAC_HDD_GetDriveCapacity(). M-RV
Changed MMAC_HDD_GetError() and
MMAC_HDD_GetStatus() to each use a single UI32
parameter.
0.06 Updated to provide an example of correct API M-RV
documentation format.
0.07 Added section for Includes and Initialisations to the M-RV
Introduction.
0.08 Added MMAC_HDD_GetData() so that applications can M-RV
read the IDE DATA register following a command being
issued with MMAC_HDD_SetFeatureRegister()
0.09 Updated information on #defined values defined in M-RV
“mmac_config.h”
0.10 Added MMAC_HDD_Seek() to API interface M-RV
0.11 Updated following HDD API Review (01/03/01) – this M-RV
updated included renaming the API to ATA API
0.12 Updating following further review (20/03/01). M-RV
0.13 Updating to include Critical Error Callback details structure M-RV
0.14 Added MMAC_ATA_INVALID_PARAM result code M-RV
0.15 Updated description of DMA read/write functions M-RV
0.16 Updated example code M-RV
0.17 Updated code example to ensure test code 'sleeps' while M-RV
waiting for the completion callback - this gives the low-
priority ATA callback task a look-in, so it is able to perform
the callback.
2001-08-09 018 Updated ‘See Also’ references in function descriptions. M-RV
Updated MMAC_ATA_MAXBYTESPERTRANSFER to 128
2002-08-06 0.19 Doc reformatted M-RJI
2002-10-01 0.20 Removed device applicability, calling mode and M-RL
atchitectural overview sections
2002-12-04 1.0 For release, same as v0.20 M-RJI

24
 Date Doc API Details of change Ref.
Ver. Ver.
2003-06-26 1.1 Doc number added. Same as v1.0 M-RJI
2005-07-14 1.2 Updated to support over 137Gb large drives J-HN

25