5.18.5 Semihosting event sources

The Semihosting API supports the following event sources.

Event source IRIS_SEMIHOSTING_OUTPUT

This event is generated by the target instance to emit bytes of semihosting output.

Table 5-10 Event source IRIS_SEMIHOSTING_OUTPUT

Field Type Description
DATA NumberU64[]

Characters (bytes) that are to be written to stdout or stderr. It can include bytes with the value of zero, and is not zero-terminated. It must not be empty.

The encoding is 8 bytes for each array element, with the first byte in the lowest bits, in other words, little-endian. The last element contains 1-8 bytes in the lowest bits.

SIZE NumberU64 Number of bytes in DATA.
FDES NumberU64 File descriptor number that is used for output. 1 means stdout and 2 means stderr. Other values have a meaning that is specific to the target instance or target application.

Event source IRIS_SEMIHOSTING_INPUT_REQUEST

This event is issued whenever the semihosting implementation starts blocking on a blocking read operation or returns no data for a non-blocking read operation. It indicates that an application requests some data.

Table 5-11 Event source IRIS_SEMIHOSTING_INPUT_REQUEST

Field Type Description
FDES NumberU64 File descriptor number used for input. This is usually 0, meaning stdin. This value should be passed to the semihosting_provideInputData() function when passing data.
NONBLOCK Boolean Optional. If present and True, this request is caused by a non-blocking read operation. Otherwise, the target instance remains in a blocking read until it receives enough data.
RAW Boolean Optional. If True, all subsequent user input should be fed into the model immediately when it becomes available, as if a terminal is switched to raw I/O. When this field is missing, or False, user input should be fed into the model when the user presses the Enter key, in other words terminal cooked mode. The user interface can allow editing the line before sending it to the model. The raw or cooked mode should stay active until the next IRIS_SEMIHOSTING_INPUT_REQUEST or IRIS_SEMIHOSTING_INPUT_UNBLOCKED event for this file descriptor.
SIZEHINT NumberU64 Number of bytes that the model consumes immediately.

Event source IRIS_SEMIHOSTING_INPUT_UNBLOCKED

This event is issued whenever a blocking semihosting read operation is unblocked.

It does not mean that no more input is required in the future. It is only a hint that the target instance is not currently blocked because of missing input. Non-blocking read operations never send this event because they never block. The raw or cooked mode should be set to cooked, see the RAW field of IRIS_SEMIHOSTING_INPUT_REQUEST.

Table 5-12 Event source IRIS_SEMIHOSTING_INPUT_UNBLOCKED

Field Type Description
FDES NumberU64 File descriptor number used for input. This is usually 0, which means stdin.

Event source IRIS_SEMIHOSTING_CALL

This event is issued just before a semihosting function is called. It can be used to monitor semihosting call usage.

Activating it does not affect the model behavior. It cannot be used to re-implement the built-in semihosting calls or to extend semihosting.

Table 5-13 Event source IRIS_SEMIHOSTING_CALL

Field Type Description
OPERATION NumberU64 The operation number of the built-in or user semihosting call according to the semihosting specification. This is the value of the operation number register when the target issues the semihosting trap instruction.
PARAMETER NumberU64 Register argument for the called function. This is the value of the parameter register when the target issues the semihosting trap instruction. This either contains an argument value for the called function, or it contains the virtual address of a data structure. This decision and the semantics depend on OPERATION. In case of a memory address, the semihosting implementation must read the memory using the memory_read() function.

Event source IRIS_SEMIHOSTING_CALL_EXTENSION

This event source is intrusive. Activating it changes the model behavior. When it is active, this event is issued instead of a built-in semihosting function call.

The receiver of this event is expected to implement and execute the semihosting call from within the event callback. This event source should be activated with eventStream_create(syncEc=True).

Note:

All synchronous event activity across IPC has a severe performance impact.

The ec_FOO() callback must do one of the following:

  • Execute the semihosting function, and therefore override the built-in implementation. In this case it must call semihosting_return(). semihosting_return() must not be called from any other event callback, otherwise E_invalid_context is returned. Functions that need to return more data than an integer should write it directly into memory using memory_write(). A buffer consisting of a memory address and length is usually passed to the called function as an argument for this purpose.
  • Leave execution to the built-in implementation, and therefore do not override it. In this case, it must call semihosting_notImplemented().
  • Leave execution to the next client that registered this event source. If multiple clients have registered this event source, any of them might be called first and have the choice to implement the function or pass it to the next one, in no defined order. This enables different plug-ins to override separate, non-overlapping, sets of functions.

Table 5-14 Event source IRIS_SEMIHOSTING_CALL_EXTENSION

Field Type Description
OPERATION NumberU64 The operation number of the built-in or user semihosting call according to the semihosting specification. This is the value of the operation number register when the target issues the semihosting trap instruction.
PARAMETER NumberU64 Register argument for the called function. This is the value of the parameter register when the target issues the semihosting trap instruction. This either contains an argument value for the called function, or it contains the virtual address of a data structure. This decision and the semantics depend on OPERATION. In case of a memory address, the semihosting implementation must read the memory using the memory_read() function.
Non-ConfidentialPDF file icon PDF version101196_0100_03_en
Copyright © 2018, 2019 Arm Limited or its affiliates. All rights reserved.