src/arch/xtensa/include/xtensa/xtbsp.h

/*******************************************************************************

  Copyright (c) 2006-2009 Tensilica Inc.

  Permission is hereby granted, free of charge, to any person obtaining
  a copy of this software and associated documentation files (the
  "Software"), to deal in the Software without restriction, including
  without limitation the rights to use, copy, modify, merge, publish,
  distribute, sublicense, and/or sell copies of the Software, and to
  permit persons to whom the Software is furnished to do so, subject to
  the following conditions:

  The above copyright notice and this permission notice shall be included
  in all copies or substantial portions of the Software.

  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
  CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

--------------------------------------------------------------------------------

xtbsp.h     Xtensa Board Support Package API

This API defines a minimal set of board-support functions that every supported
Xtensa board is expected to provide in the board-support-package (BSP) library
associated with the board-specific LSP. Only basic board functions are provided
in this board-independent API. API functions not applicable to a board must be
stubbed in its BSP library. More complex operations must use a board-specific
interface. Functions are grouped by type of peripheral device.

*******************************************************************************/

#ifndef _XTBSP_H_
#define _XTBSP_H_


#ifdef __cplusplus
extern  "C" {
#endif

  
/*******************************************************************************
BOARD INITIALIZATION.
The board with all its devices is initialized by xtbsp_board_init().
Individual devices represented by this API can be reinitialized at any 
time by calling their inidividual device init functions (grouped with 
other device functions). This might be useful to (say) change the baud 
rate of the UART.
*/


/*
Initialize the board. Must call before any other API function.
Iniitializes BSP, board in general, and all devices on the board.
*/
extern void xtbsp_board_init(void);


/*******************************************************************************
BOARD CHARACTERISTICS and CONVENIENCE FUNCTIONS.
Board support functions not associated with a particular peripheral device.
*/

/*
Return a short string representing the type of board.
If the board has a display, the string must fit on a single line.
*/
extern const char * xtbsp_board_name(void);

/*
Hardware reset the entire board (if possible). Does not return if successful.
If this function returns, it is stubbed out or not possible with this board.
*/
extern void xtbsp_board_reset(void);

/*
Return the clock frequency in Hertz. May be constant or computed.
*/
extern unsigned xtbsp_clock_freq_hz(void);

/*
Return the clock period in picoseconds. May be constant or computed.
*/
extern unsigned xtbsp_clock_period_ps(void);

/*
Spin (at least) a number of cycles per the processor's CCOUNT register.
Unlike a s/w delay loop, the duration is not affected by compiler
optimization or interrupts completed within the delay period.
If the processor doesn't have CCOUNT, a s/w delay loop is used to obtain 
a rough approximation of the cycle count.
*/
extern void xtbsp_delay_cycles(unsigned cycles);

/*
Spin at least a number of nanoseconds (approximate and err in the high side).
BSP implementation should do this efficiently, avoiding integer overflow or 
excessive loss of precision, run-time division or floating point. 
Function implementation (vs. macro) allows BSP to optimize for the clock 
frequency by pre-computing (or using constant) scale factors.
*/
extern void xtbsp_delay_ns(unsigned ns);


/*******************************************************************************
C LIBRARY SUPPORT.
These functions are called by the C library libgloss interface.
Their names are predetermined apart from this BSP API.
*/

/*
Initialize the board. Called by C library initialization code.
Usually simply calls xtbsp_board_init().
*/
extern void board_init(void);

/*
(Wait for and) Input a single byte from the default character I/O 
device. Return -1 if there is no input device. 
This device is usually a UART and this function calls xtbsp_uart_getchar().
On some boards (eg.) it might be a directly connected keyboard.
*/
extern int inbyte(void);

/*
Output a single char to the default character I/O device (and wait 
until it's been taken). 
This device is usually a UART and this function calls xtbsp_uart_putchar().
On some boards (eg.) it might be a directly connected bit-mapped screen.
*/
extern void outbyte(int c);


/*******************************************************************************
UART (SERIAL I/O).
Supports a single UART in a simple polling mode and provides control of
receiver and transmitter data interrupts (client must provide handler).
Provides a mapping to processor interrupt number which can be used with
the HAL to control processor interrupt enable (INTENABLE) etc.
*/

/* Bitmasks to identify UART interrupts. */
typedef enum xtbsp_uart_int {
    xtbsp_uart_int_rx = 1<<0,
    xtbsp_uart_int_tx = 1<<1,
    /* mask of all valid interrupt bits */
    xtbsp_uart_int_all = (1<<2)-1
} xtbsp_uart_int;

/*
Return non-zero if the board has a UART.
*/
extern int xtbsp_uart_exists(void);

/*
Initialize the UART:
  parity = 0 (none), 1 (odd), or 2 (even).
  nstop  = 1 or 2 (stop bits).
  ndata  = 7 or 8 (data bits).
Disables all UART interrupts.
Returns non-zero if failed (perhaps due to unsupported parameter values).
Must call before any of the following functions.
*/
extern int xtbsp_uart_init(unsigned baud, unsigned ndata, 
                           unsigned parity, unsigned nstop);
#define xtbsp_uart_init_default() xtbsp_uart_init(38400, 8, 0, 1)

/*
 Extended init routine for 'portable' UART. Allows specifying the UART
 base address and interrupt number (if interrupt operation desired).
 Meant for use on platforms other than the FPGA boards (e.g. XTSC sim
 or Palladium).

 NOTE: Using the 'portable' UART may require that you implement function
 xtbsp_clock_freq_hz() if your target platform does not provide it.
 We recommend you implement it as a weak function so that it can be
 overridden by the target platform implementation if available.
 */
extern int xtbsp_uart_init_ex(unsigned uart_baseaddr,
                              unsigned uart_intnum,
                              unsigned baud,
                              unsigned ndata,
                              unsigned parity,
                              unsigned nstop);

/*
(Wait for and) Input a single char from the UART.
Any pending xtbsp_uart_int_rx interrupt is cleared.
*/
extern char xtbsp_uart_getchar(void);

/*
(Wait for transmitter ready and) Output a single char to the UART.
Any pending xtbsp_uart_int_tx interrupt is cleared.
*/
extern void xtbsp_uart_putchar(const char c);

/*
Return true (non-zero) if a character has been received and is ready
to be input by xtbsp_uart_getchar() without waiting, else return 0.
*/
extern int xtbsp_uart_get_isready(void);

/*
Return non-zero if a character may be output by xtbsp_uart_putchar() 
without waiting, else return 0.
Any pending xtbsp_uart_int_tx interrupt is cleared.
*/
extern int xtbsp_uart_put_isready(void);

/*
Return the enable status of all UART interrupts represented by this API,
that is those with bits defined in type xtbsp_uart_int (1 bit = enabled).
This is the enable status at the device, not the processor's INTENABLE.
*/
extern xtbsp_uart_int xtbsp_uart_int_enable_status(void);

/*
Enable selected UART interrupts at the device.
*/
extern void xtbsp_uart_int_enable(const xtbsp_uart_int mask);

/*
Disable selected UART interrupts at the device.
*/
extern void xtbsp_uart_int_disable(const xtbsp_uart_int mask);

/*
Return the interrupt number (0..31) to which the selected UART interrupt
is connected. May be used with the link-time HAL to obtain more information,
eg. Xthal_intlevel_mask[xtbsp_uart_int_number(xtbsp_uart_int_rx)]
This information can be used to control the processor's INTENABLE, etc.
Result is -1 if not connected, undefined if mask has more than 1 bit set.
*/
extern int xtbsp_uart_int_number(const xtbsp_uart_int mask);


/*******************************************************************************
DISPLAY.
Supports a single display that can render a series of ASCII characters.
Functions are provided to perform generic display tasks such as display
a string, display character by character, or blank the display.
Chars are 7-bit printable ASCII. Strings are C style NUL \0 terminated.
These functions busy-wait for any required timing delays so the caller does
not have to deal with timing. Some displays require long delays which in 
some client applications warrant a board and RTOS specific approach to 
driving the display, however that is beyond the scope of this API.
*/

/*
Return non-zero if board has a display.
*/
extern int xtbsp_display_exists(void);

/*
Initialize the display. Must call before any of the following functions.
*/
extern void xtbsp_display_init(void);

/*
Display a single char at position pos (0 is leftmost). Other positions are
left untouched. Positions beyond the width of the display are ignored.
*/
extern void xtbsp_display_char(unsigned pos, const char c);

/*
Display a string. Blank-pad to or truncate at the end of the display
(overwrites any previous string so don't need to blank display first).
*/
extern void xtbsp_display_string(const char *s);

/*
Blank (clear) the entire display.
*/
extern void xtbsp_display_blank(void);



#ifdef __cplusplus
}
#endif

#endif /* _XTBSP_H_ */