API - HAL

The hal API is made up of several subsystems that each operate independantly of one another. This document describes the available APIs and gives some advice and examples on the usage of each.

General XBOX Functionality

FunctionDescription
void XReboot()Reboots the XBOX. Note that this reboot takes the XBOX right back to the very start of its boot cycle. You have some level of control over this. Check out the xboxkrnl library's call to HalReturnToFirmware function.
void XLaunchXBE(
  char *xbePath
)
Launches an XBE (replacing the currently running XBE). If the launch is successful, this method will not return. If there is an error, it returns and you will have to decide what to do.

ParameterDescription
xbePathFully qualified dos path of the XBE. Example: c:/foo/bar.xbe

void XSleep(
  int milliseconds
)
Sleeps for the specific number of milliseconds. At the moment, it is in a tight loop, so it is not very thread friendly. One of these days, I will get around to calling a proper xboxkrnl API (once I figure out which one it is)

ParameterDescription
millisecondsThe length of time to sleep

int XGetTickCount()Returns the current kernel tick count (which is the number of milliseconds since the XBOX was turned on).
int XCreateThread(
  XThreadCallback callback,
  void *args1,
  void *args2
);
Creates and runs a new thread.

ParameterDescription
callbackThe entry point of the thread function. It must be a static function that takes two void * paramaters
args1This will be passed to the callback function as the first parameter
args2This will be passed to the callback function as the second parameter

File Access

All of the file access APIs return a status code that you should compare against STATUS_SUCCESS.

FunctionDescription
int XConvertDOSFilenameToXBOX(
  char *dosFilename,
  char *xboxFilename
)
Converts a dos-style filename (c:/foo/bar.txt) into an XBOX-style path (\Device\Harddisk0\Partition2\foo\bar.txt).

ParameterDescription
dosFilenameThe dos filename. Examples are c:\foo\bar.txt, .\foo\bar.txt, \foo\bar.txt
xboxFilenameThe converted XBOX filename

int XCreateFile(
  int *handle,
  char *filename,
  unsigned int desiredAccess,
  unsigned int sharedMode,
  unsigned int creationDisposition,
  unsigned int flagsAndAttributes
)
Opens a file. Note that the title of the function is slightly misleading in that this function may not actually create a file... it may just open an existing one (depending on the combination of the various parameters. For more information on the combinations of the various parameters, see the Microsoft CreateFile documentation.

ParameterDescription
handleThe handle to the opened file
filenameThe file to open. Examples of supported filenames are: c:/blah.txt, blah.txt, d:\default.txt
desiredAccessBitwise OR of one or more of the following options:
  • DELETE
  • SYNCHRONIZE
  • GENERIC_ALL
  • GENERIC_EXECUTE
  • GENERIC_WRITE
  • GENERIC_READ
sharedModeBitwise OR of one or more of the following options:
  • FILE_SHARE_READ
  • FILE_SHARE_WRITE
  • FILE_SHARE_DELETE
creationDispositionBitwise OR of one or more of the following options:
  • CREATE_NEW
  • CREATE_ALWAYS
  • OPEN_EXISTING
  • OPEN_ALWAYS
  • TRUNCATE_EXISTING
flagsAndAttributesBitwise OR of one or more of the following options (normally, you would just use FILE_ATTRIBUTE_NORMAL):
  • FILE_FLAG_OPEN_NO_RECALL
  • FILE_FLAG_OPEN_REPARSE_POINT
  • FILE_FLAG_POSIX_SEMANTICS
  • FILE_FLAG_BACKUP_SEMANTICS
  • FILE_FLAG_DELETE_ON_CLOSE
  • FILE_FLAG_SEQUENTIAL_SCAN
  • FILE_FLAG_RANDOM_ACCESS
  • FILE_FLAG_NO_BUFFERING
  • FILE_FLAG_OVERLAPPED
  • FILE_FLAG_WRITE_THROUGH
  • FILE_ATTRIBUTE_READONLY
  • FILE_ATTRIBUTE_HIDDEN
  • FILE_ATTRIBUTE_SYSTEM
  • FILE_ATTRIBUTE_DIRECTORY
  • FILE_ATTRIBUTE_ARCHIVE
  • FILE_ATTRIBUTE_DEVICE
  • FILE_ATTRIBUTE_NORMAL
  • FILE_ATTRIBUTE_TEMPORARY
  • FILE_ATTRIBUTE_SPARSE_FILE
  • FILE_ATTRIBUTE_REPARSE_POINT
  • FILE_ATTRIBUTE_COMPRESSED
  • FILE_ATTRIBUTE_OFFLINE
  • FILE_ATTRIBUTE_NOT_CONTENT_INDEXED
  • FILE_ATTRIBUTE_ENCRYPTED
  • FILE_ATTRIBUTE_VALID_FLAGS
  • FILE_ATTRIBUTE_VALID_SET_FLAGS

int XReadFile(
  int handle,
  void *buffer,
  unsigned int numberOfBytesToRead,
  unsigned int *numberOfBytesRead
)
Reads data from an already opened file.

ParameterDescription
handleThe handle to the opened file
bufferThe char buffer to put the data into
numberOfBytesToReadHow many bytes to read
numberOfBytesReadHow many bytes were actually read from the file

int XWriteFile(
  int handle,
  void *buffer,
  unsigned int numberOfBytesToWrite,
  unsigned int *numberOfBytesWritten
)
Writes data to an already opened file.

ParameterDescription
handleThe handle to the opened file
bufferThe char buffer to get the data from
numberOfBytesToWriteHow many bytes to write
numberOfBytesWrittenHow many bytes were actually written to the file

int XCloseHandle(
  int handle
)
Seems fairly obvious doesn't it? Closes the file.

ParameterDescription
handleThe handle to the opened file

int XGetFileSize(
  int handle,
  unsigned int *filesize
)
Queries the file size of a given file.

ParameterDescription
handleThe handle to the opened file
filesizeThis variable is updated with the file's size

int XSetFilePointer(
  int handle,
  int distanceToMove,
  int *newFilePointer,
  int moveMethod
)
Seeks to a location within an open file.

ParameterDescription
handleThe handle to the opened file
distanceToMoveThe distance to seek (can be negative).
newFilePointerUpdated with the new absolute offset within the file
moveMethodOne of the following options:
  • FILE_BEGIN
  • FILE_CURRENT
  • FILE_END

int XRenameFile(
  char *oldFilename,
  char *newFilename
)
Renames a file

ParameterDescription
oldFilenameThe file to rename
newFilenameThe new file name

int XCreateDirectory(
  char *directoryName
)
Create a new directory

ParameterDescription
directoryNameThe directory name

int XDeleteFile(
  char *filename
)
Deletes a file.

ParameterDescription
filenameThe name of the file to delete

int XDeleteDirectory(
  char *directoryName
)
Deletes a directory

ParameterDescription
directoryNameThe name of the directory to delete

int XMountDrive(
  char driveLetter,
  char *directoryName
)
Assigns the given drive letter to the directoryName.

ParameterDescription
driveLetterThe drive letter to assign. For example, 'd'
directoryNameThe directory that will be referred to as driveLetter from now on (until next reboot). It should contain a trailing slash, but if you forget, one will be added for you.

unsigned int XFindFirstFile(
  char *directoryName,
  char *mask,
  PXBOX_FIND_DATA findFileData
)
Performs a very similar function to the Win32 FindFirstFile, in that it populates (for the first file within the directoryName directory) the findFileData data structure. Returns ERROR_INVALID_HANDLE if the directory is unable to be opened or is invalid, otherwise a valid file handle for the directory (which you should pass to XFindNextFile to get the next file in the list).

The elements of the data structure are:

typedef struct _XBOX_FIND_DATA
{
  unsigned int dwFileAttributes;
  long long ftCreationTime;
  long long ftLastAccessTime;
  long long ftLastWriteTime;
  unsigned int nFileSize;
  char cFileName[0x100];
} XBOX_FIND_DATA, *PXBOX_FIND_DATA;

ParameterDescription
directoryNameThe directory that contains the file you care about
maskA mask for the files you want. For example, "*.xbe" for all XBE files or "*" for all files
fileFileDataThe data structure that will be populated with the file details (name, size, etc)

int XFindNextFile(
  unsigned int handle,
  PXBOX_FIND_DATA findFileData
)
Gets the next file from the directory that was opened using XFindFirstFile. Returns ERROR_NO_MORE_FILES if there are no more files, 0 otherwise.

ParameterDescription
handleThe handle that was returned from XFindFirstFile
fileFileDataThe data structure that will be populated with the file details (name, size, etc)

int XFindClose(
  unsigned int handle
)
Closes the handle that was opened when calling XFindFirstFile

ParameterDescription
handleThe handle that was returned from XFindFirstFile

Controllers

Currently only one pad is supported. Details of XPadState are as follows:
typedef struct
{
  char reserved1;
  unsigned char structsize;

  char pad;       /* 1=up 2=down 4=left 8=right + bitwise OR combos */
  char reserved2;
  char keys[6];   /* A B X Y Black White */

  unsigned char trig_left;
  unsigned char trig_right;
  short stick_left_x;
  short stick_left_y;
  short stick_right_x;
  short stick_right_y;

  char padding[0x40];
} XPadState;

FunctionDescription
void XInitInput(
  XUSBControl *xcontrol
)
Initialises the XBOX controller USB subsystem. This function must be called before calling any of the other controller functions.

ParameterDescription
xcontrolA pointer to a control structure that will be initialised. This control structure will be used in subsequent calls.

void XGetPadInput(
  XPadState *padState,
  XUSBControl *xcontrol,
  int padNumber
)
Reads the current state of the XBOX controllers

ParameterDescription
padStateA pointer to a XPadState structure that will contain the current state
xcontrolThe pointer to the control structure
padNumberWhich pad number are you querying?

void XSetPadInput(
  XPadState *padState,
  XUSBControl *xcontrol,
  int padNumber
)
Updates the current state of the XBOX controllers (sends a message). This function is a bit dodgy at the moment... use at your own risk!

ParameterDescription
padStateA pointer to a XPadState structure
xcontrolThe pointer to the control structure
padNumberWhich pad number are you updating?

void XReleaseInput(
  XUSBControl *xcontrol
)
Shuts down the XBOX controller subsystem. If you call this, you will need to call XInitInput again before you can interact with the controllers.

ParameterDescription
xcontrolThe pointer to the control structure

Video

FunctionDescription
DWORD XVideoGetEncoderSettings();Returns the current video encoder settings.
unsigned char* XVideoGetFB()Returns a pointer to the XBOX's raw video buffer.
VIDEO_MODE XVideoGetMode() Returns a structure that represents the current video mode. The elements of the structure are described below:

typedef struct _VIDEO_MODE
{
  int width;
  int height;
  int bpp;
  int refresh;
} VIDEO_MODE;

void XVideoSetFlickerFilter(
  int level
);
Sets the level of flicker filter to an appropriate level.

ParameterDescription
levelThe level of flicker filter to apply (should be between X and X)

BOOL XVideoSetMode(
  int width,
  int height,
  int bpp,
  int refresh
);
Requests that the video mode be set to the requested mode. This function does some validation to ensure that the requested parameters are valid. Typical invocations might be:

XVideoSetMode(640, 480, 24, 50); /* for PAL */
XVideoSetMode(640, 480, 24, 60); /* for NTSC */
XVideoSetMode(720, 480, 24, 50); /* for PAL */
XVideoSetMode(720, 480, 24, 60); /* for NTSC */

Returns a boolean indicating whether the mode was able to be changed.

ParameterDescription
widthThe desired screen width
heightThe desired screen height
bppThe desired screen bits per pixel
refreshThe desired refresh rate in Hz

void XVideoSetSoftenFilter(
  BOOL enable
);
Sets the soften filter

ParameterDescription
enableWhether the soften filter should be enabled or not

void XVideoSetVideoEnable(
  BOOL enable
);
Enables the video subsystem

ParameterDescription
enableWhether the video should be enabled

Audio

The audio support is functional, but experimental. When using the audio subsystem the first thing you need to do is initialise by calling XAudioInit(). This does not actually start playing anything, though. To get that to work, you will need to call XAudioPlay() (and likewise, to temporarily pause, you call XAudioPause()).

However, it is not much good playing unless you have given it some data to play. To give data to the audio subsystem, you need to call XAudioProvideSamples(). There are two supported ways of calling this method:

  1. Your application code can call XAudioProvideSamples() based on its own timing. It is your code's responsibility to make sure you are calling this function often enough.
  2. You can register a callback when you initialise and the audio subsystem will invoke your callback function when it needs more data. This callback function provides the data using a call to XAudioProvideSamples().
FunctionDescription
void XAudioInit(
  int sampleSizeInBits,
  int numChannels,
  XAudioCallback callback,
  void *data
);
Initialises the audio subsystem. It does not start playing though.

ParameterDescription
sampleSizeInBitsCurrently ignored (only 16 bit samples are supported at the moment). Provided for future expandability
numChannelsCurrently ignored (only 2 channels (stereo) are supported at the moment). Provided for future expandability
callbackIf non-NULL, this is the function that will be called by the audio subsystem when it needs more data.
dataThis will be passed to the callback function (if the callback is set) when it is invoked

int XAudioPlay()Tells the audio chip to start playing.
int XAudioPause()Tells the audio chip to pause
void XAudioProvideSamples(
  unsigned char *buffer,
  unsigned short bufferLength,
  int isFinal
);
Gives some more data to the audio subsystem to play. You should call this often enough so that the chip doesn't run out of data, but not faster than the audio chip can process it (48kHz). Using the callback parameter in XAudioInit() may help.

ParameterDescription
bufferA pointer to the samples which need to match the sampleSizeInBits and numChannels. For example, a 16 bit stereo sample would be 4 bytes in the following order: [ Left LSB, Left MSB, Right LSB, Right MSB ]
bufferLengthThe length of the data contained in buffer.
isFinalIf this the last lot of data to be played?



Back to Home Page