OpenCores
URL https://opencores.org/ocsvn/openrisc_2011-10-31/openrisc_2011-10-31/trunk

Subversion Repositories openrisc_2011-10-31

[/] [openrisc/] [trunk/] [or1ksim/] [doc/] [or1ksim.texi] - Diff between revs 430 and 432

Go to most recent revision | Show entire file | Details | Blame | View Log

Rev 430 Rev 432
Line 645... Line 645...
library, the flag, @code{-lsim} should be added to the link command.
library, the flag, @code{-lsim} should be added to the link command.
 
 
The header file @file{or1ksim.h} contains appropriate declarations of
The header file @file{or1ksim.h} contains appropriate declarations of
the functions exported by the @value{OR1KSIM} library.  These are:
the functions exported by the @value{OR1KSIM} library.  These are:
 
 
@deftypefn {@file{or1ksim.h}} int or1ksim_init (int @var{argc}, char *@var{argv}, void *@var{class_ptr},
@deftypefn {@file{or1ksim.h}} int or1ksim_init (int @var{argc}, @
int (*@var{upr})(void *@var{class_ptr}, unsigned long int @var{addr},
           char *@var{argv}, void *@var{class_ptr}, @
unsigned char @var{mask}[], unsigned char @var{rdata}[], int
           int (*@var{upr})(void *@var{class_ptr}, @
@var{data_len}), int (*@var{upw})(void *@var{class_ptr}, unsigned long
           unsigned long int @var{addr}, unsigned char @var{mask}[], @
int @var{addr}, unsigned char @var{mask}[], unsigned char @var{wdata}[],
           unsigned char @var{rdata}[], int @var{data_len}), @
 
           int (*@var{upw})(void *@var{class_ptr}, @
 
           unsigned long int @var{addr}, @
 
           unsigned char @var{mask}[], unsigned char @var{wdata}[], @
int @var{data_len}))
int @var{data_len}))
 
 
The initialization function is supplied with a vector of arguments,
The initialization function is supplied with a vector of arguments,
which are interpreted as arguments to the standalone version (see
which are interpreted as arguments to the standalone version (see
@pxref{Standalone Simulator, , Standalone Simulator}), a pointer to the
@pxref{Standalone Simulator, , Standalone Simulator}), a pointer to the
Line 751... Line 754...
 
 
@end deftypefn
@end deftypefn
 
 
@deftypefn {@file{or1ksim.h}} void or1ksim_interrupt (int  @var{i})
@deftypefn {@file{or1ksim.h}} void or1ksim_interrupt (int  @var{i})
 
 
Generate an edge-triggered interrupt on interrupt line @var{i}.  The interrupt
Generate an edge-triggered interrupt on interrupt line @var{i}.  The
is then immediately cleared automatically.  A warning will be generated and the
interrupt must be cleared separately by clearing the corresponding bit
interrupt request ignored if level sensitive interrupts have been configured
in the PICSR SPR.  Until the interrupt is cleared, any further
with the programmable interrupt controller (@pxref{Interrupt Configuration, ,
interrupts on the same line will be ignored with a warning.  A warning
Interrupt Configuration}).
will be generated and the interrupt request ignored if level sensitive
 
interrupts have been configured with the programmable interrupt
 
controller (@pxref{Interrupt Configuration, , Interrupt Configuration}).
 
 
@end deftypefn
@end deftypefn
 
 
@deftypefn {@file{or1ksim.h}} void or1ksim_interrupt_set (int  @var{i})
@deftypefn {@file{or1ksim.h}} void or1ksim_interrupt_set (int  @var{i})
 
 
Assert a level-triggered interrupt on interrupt line @var{i}.  The interrupt
Assert a level-triggered interrupt on interrupt line @var{i}.  The
must be cleared separately by an explicit call to
interrupt must be cleared separately by an explicit call to
@code{or1ksim_interrupt_clear}.  A warning will be generated, and the interrupt
@code{or1ksim_interrupt_clear}.  Until the interrupt is cleared, any
request ignored if edge sensitive interrupts have been configured with the
further setting of interrupts on the same line will be ignored with a
programmable interrupt controller (@pxref{Interrupt Configuration, , Interrupt
warning.  A warning will be generated, and the interrupt request ignored
 
if edge sensitive interrupts have been configured with the programmable
 
interrupt controller (@pxref{Interrupt Configuration, , Interrupt
Configuration}).
Configuration}).
 
 
@end deftypefn
@end deftypefn
 
 
@deftypefn {@file{or1ksim.h}} void or1ksim_interrupt_clear (int  @var{i})
@deftypefn {@file{or1ksim.h}} void or1ksim_interrupt_clear (int  @var{i})
Line 789... Line 796...
which can be an order of magnitude slower than the main clock, so even a
which can be an order of magnitude slower than the main clock, so even a
reset (5 JTAG cycles) could take 50 processor clock cycles to complete.
reset (5 JTAG cycles) could take 50 processor clock cycles to complete.
 
 
@end deftypefn
@end deftypefn
 
 
@deftypefn {@file{or1ksim.h}} double or1ksim_jtag_shift_ir (unsigned
@deftypefn {@file{or1ksim.h}} double or1ksim_jtag_shift_ir @
char *@var{jreg}, int @var{num_bits})
           (unsigned char *@var{jreg}, int @var{num_bits})
 
 
Shift the supplied register through the JTAG instruction register.
Shift the supplied register through the JTAG instruction register.
Return the (model) time taken for this action.  The register is supplied
Return the (model) time taken for this action.  The register is supplied
as a byte vector, with the least significant bits in the least
as a byte vector, with the least significant bits in the least
significant byte.  If the total number of bits is not an exact number of
significant byte.  If the total number of bits is not an exact number of
Line 804... Line 811...
For example a 12-bit register would have bits 0-7 in byte 0 and bits
For example a 12-bit register would have bits 0-7 in byte 0 and bits
11-8 in the least significant 4 bits of byte 1.
11-8 in the least significant 4 bits of byte 1.
 
 
@end deftypefn
@end deftypefn
 
 
@deftypefn {@file{or1ksim.h}} double or1ksim_jtag_shift_dr (unsigned
@deftypefn {@file{or1ksim.h}} double or1ksim_jtag_shift_dr @
char *@var{jreg}, int @var{num_bits})
           (unsigned char *@var{jreg}, int @var{num_bits})
 
 
Shift the supplied register through the JTAG data register.  Return the
Shift the supplied register through the JTAG data register.  Return the
(model) time taken for this action.  The register is supplied as a byte
(model) time taken for this action.  The register is supplied as a byte
vector, with the least significant bits in the least significant byte.
vector, with the least significant bits in the least significant byte.
If the total number of bits is not an exact number of bytes, then the
If the total number of bits is not an exact number of bytes, then the
Line 819... Line 826...
For example a 12-bit register would have bits 0-7 in byte 0 and bits
For example a 12-bit register would have bits 0-7 in byte 0 and bits
11-8 in the least significant 4 bits of byte 1.
11-8 in the least significant 4 bits of byte 1.
 
 
@end deftypefn
@end deftypefn
 
 
@deftypefn {@file{or1ksim.h}} int or1ksim_read_mem (unsigned
@deftypefn {@file{or1ksim.h}} int or1ksim_read_mem @
long int @var{addr}, unsigned char *@var{buf}, int @var{len})
           (unsigned long int @var{addr}, unsigned char *@var{buf}, @
 
           int @var{len})
 
 
Read @var{len} bytes from @var{addr}, placing the result in @var{buf}.
Read @var{len} bytes from @var{addr}, placing the result in @var{buf}.
Return @var{len} on success and 0 on failure.
Return @var{len} on success and 0 on failure.
 
 
@quotation Note
@quotation Note
This function was added in Or1ksim 0.5.0.
This function was added in Or1ksim 0.5.0.
@end quotation
@end quotation
 
 
@end deftypefn
@end deftypefn
 
 
@deftypefn {@file{or1ksim.h}} int or1ksim_write_mem (unsigned
@deftypefn {@file{or1ksim.h}} int or1ksim_write_mem @
long int @var{addr}, const unsigned char *@var{buf}, int @var{len})
           (unsigned long int @var{addr}, const unsigned char *@var{buf}, @
 
           int @var{len})
 
 
Write @var{len} bytes to @var{addr}, taking the data from @var{buf}.
Write @var{len} bytes to @var{addr}, taking the data from @var{buf}.
Return @var{len} on success and 0 on failure.
Return @var{len} on success and 0 on failure.
 
 
@quotation Note
@quotation Note
This function was added in Or1ksim 0.5.0.
This function was added in Or1ksim 0.5.0.
@end quotation
@end quotation
 
 
@end deftypefn
@end deftypefn
 
 
@deftypefn {@file{or1ksim.h}} int or1ksim_read_spr (int @var{sprnum}, unsigned
@deftypefn {@file{or1ksim.h}} int or1ksim_read_spr (int @var{sprnum}, @
long int *@var{sprval_ptr})
           unsigned long int *@var{sprval_ptr})
 
 
Read the SPR specified by @var{sprnum}, placing the result in
Read the SPR specified by @var{sprnum}, placing the result in
@var{sprval_ptr}.  Return non-zero on success and 0 on failure.
@var{sprval_ptr}.  Return non-zero on success and 0 on failure.
 
 
@quotation Note
@quotation Note
This function was added in Or1ksim 0.5.0.
This function was added in Or1ksim 0.5.0.
@end quotation
@end quotation
 
 
@end deftypefn
@end deftypefn
 
 
@deftypefn {@file{or1ksim.h}} int or1ksim_write_spr (int @var{sprnum}, unsigned
@deftypefn {@file{or1ksim.h}} int or1ksim_write_spr (int @var{sprnum}, @
long int @var{sprva})
           unsigned long int @var{sprva})
 
 
Write @var{sprval} to the SPR specified by @var{sprnum}.  Return
Write @var{sprval} to the SPR specified by @var{sprnum}.  Return
non-zero on success and 0 on failure.
non-zero on success and 0 on failure.
 
 
@quotation Note
@quotation Note
This function was added in Or1ksim 0.5.0.
This function was added in Or1ksim 0.5.0.
@end quotation
@end quotation
 
 
@end deftypefn
@end deftypefn
 
 
@deftypefn {@file{or1ksim.h}} int or1ksim_read_reg (int @var{regnum}, unsigned
@deftypefn {@file{or1ksim.h}} int or1ksim_read_reg (int @var{regnum}, @
long int *@var{regval_ptr})
           unsigned long int *@var{regval_ptr})
 
 
Read the general purpose register specified by @var{regnum}, placing the
Read the general purpose register specified by @var{regnum}, placing the
result in @var{regval_ptr}.  Return non-zero on success and 0 on
result in @var{regval_ptr}.  Return non-zero on success and 0 on
failure.
failure.
 
 
Line 880... Line 889...
This function was added in Or1ksim 0.5.0.
This function was added in Or1ksim 0.5.0.
@end quotation
@end quotation
 
 
@end deftypefn
@end deftypefn
 
 
@deftypefn {@file{or1ksim.h}} int or1ksim_write_reg (int @var{regnum}, unsigned
@deftypefn {@file{or1ksim.h}} int or1ksim_write_reg (int @var{regnum}, @
long int @var{regva})
           unsigned long int @var{regva})
 
 
Write @var{regval} to the general purpose register specified by
Write @var{regval} to the general purpose register specified by
@var{regnum}.  Return non-zero on success and 0 on failure.
@var{regnum}.  Return non-zero on success and 0 on failure.
 
 
@quotation Note
@quotation Note
This function was added in Or1ksim 0.5.0.
This function was added in Or1ksim 0.5.0.
@end quotation
@end quotation
 
 
@end deftypefn
@end deftypefn
 
 
@deftypefn {@file{or1ksim.h}} void or1ksim_set_stall_state (int
@deftypefn {@file{or1ksim.h}} void or1ksim_set_stall_state (int @var{state})
@var{state})
 
 
 
Set the processor's state according to @var{state} (1 = stalled, 0 = not
Set the processor's state according to @var{state} (1 = stalled, 0 = not
stalled).
stalled).
 
 
@quotation Note
@quotation Note
Line 1891... Line 1899...
@item edge_trigger = 0|1
@item edge_trigger = 0|1
@cindex @code{edge_trigger} (interrupt controller)
@cindex @code{edge_trigger} (interrupt controller)
If 1 (true, the default), the programmable interrupt controller is
If 1 (true, the default), the programmable interrupt controller is
edge triggered.  If 0 (false), it is level triggered.
edge triggered.  If 0 (false), it is level triggered.
 
 
@quotation Note
The library interface (@pxref{Simulator Library, , Simulator Library})
When configured to be edge triggered, interrupts must be cleared in the PICSR by the processor writing a '0' to the appropriate bit.
provides different functions for setting the different types of
 
interrupt, and a function to clear level sensitive interrupts. Edge
When configured to be level triggered, the interrupt must be cleared by lowering the peripheral's IRQ line. Writing '0' to the PICSR has no effect.
sensitive interrupts must be cleared by clearing the corresponding bit
 
in the PICSR SPR.
Peripherals can call the function @code{report_interrupt} to signal an interrupt request. When configured for level triggered interrupts, the function @code{clear_interrupt} will clear the appropriate bit in the PICSR. @code{clear_interrupt} has no effect when @value{OR1KSIM} is configured for edge triggered interrupts - interrupts must be cleared by the processor writing '0' to the appropriate bit in the PICSR in this case.
 
 
Internal functions to set and clear interrupts are also provided for
 
peripherals implemented within Or1ksim. @xref{Interrupts Internal, ,
 
Interrupts Internal} for more details.
 
 
 
@item use_nmi = 0|1
 
@cindex @code{use_nmi} (interrupt controller)
 
If 1 (true, the default), interrupt lines 0 and 1 are non-maskable. In
 
other words the least significant 2 bits of the PICMR SPR are hard-wired
 
to 1.  If 0 (false), all interrupt lines are treated as equivalent.
 
 
 
@quotation Note
 
These are not non-maskable in the true sense that they will pre-empt
 
other interrupts.  Rather they can never be masked out using the PICMR
 
register. It is up the interrupt exception handler to give these
 
interrupt lines priority, and indeed to decide on the priority order in
 
general.
@end quotation
@end quotation
 
 
 
 
@end table
@end table
 
 
@node Power Management Configuration
@node Power Management Configuration
@subsection Power Management Configuration
@subsection Power Management Configuration
@cindex configuring power management
@cindex configuring power management
Line 3656... Line 3679...
Any peripheral may register a routine to be called when the the
Any peripheral may register a routine to be called when the the
processor is reset by calling @code{reg_sim_reset}, providing a
processor is reset by calling @code{reg_sim_reset}, providing a
function and pointer to a data structure as arguments.  On reset that
function and pointer to a data structure as arguments.  On reset that
function will be called with the data stucture pointer as argument.
function will be called with the data stucture pointer as argument.
 
 
 
@anchor{Interrupts Internal}
 
@item Interrupts
 
@cindex interrupts
 
@findex report_interrupt
 
@findex clear_interrupt
 
@findex mtspr
 
An internal peripheral can model the effect of an interrupt being
 
asserted by calling @code{report_interrupt}.  This is used for both edge
 
and level sensitive interrupts.
 
 
 
The effect is to set the corresponding bit in the PICSR SPR and to queue
 
an interrupt exception to take place after the current instruction
 
completes execution.
 
 
 
Externally, the different interrupts require different mechanisms for
 
clearing.  Level sensitive interrupts should be cleared by deasserting
 
the interrupt line, edge sensitive interrupts by clearing the
 
corresponding bit in the PICSR SPR.
 
 
 
Internally this amounts to the same thing (clearing the PICSPR bit), so
 
a single function is provided, @code{clear_interrupt}.  Note however that
 
when level sensitive interrupts are configured, PICSR is read only, and
 
can only be cleared by calling @code{clear_interrupt}.  Using the two
 
functions provided will ensure the peripheral works correctly whichever
 
type of interrupt is used.
 
 
 
@quotation Note
 
Until an interrupt is cleared, all subsequent interrupts are ignored
 
with a warning.
 
@end quotation
 
 
@end table
@end table
 
 
@node Internal Debugging
@node Internal Debugging
@section Internal Debugging
@section Internal Debugging
@cindex internal debugging
@cindex internal debugging

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.