User manual

76
In order to perform the operation, the initiator invokes a routine identified by the
create_io_space field of the chapi_in descriptor. The initiator is to provide the initial bus
location of the I/O space in the addr and the len arguments. The combination of the addr
and the len shall meet the following requirements:
 The length of address range indicated by the len must be a power of two. Or more
formally:
(len & (len - 1)) == 0
 The address range shall be naturally aligned. Which means that the addr shall be
aligned to a boundary that is a multiple of len. Or more formally:
(addr + (len - 1)) == (addr | (len - 1))
The procedure is invoked as follows:
io_space_id_t sid = 0;
const chapi_in * ci = …;
if (ci->create_io_space) {
sid = ci->create_io_space(ci, addr, len);
}
if (sid == 0) {
/* failed to create the io space*/
}
The example above shows that the CHARON core is not obliged to support the indicated
operation. Also it gives a clue why the device instance is supposed to remember the
chapi_in descriptor.
In the example above the device is supposed to store the (non-zero) result of the
create_io_space procedure. Later this value is to be used as I/O space identifier for
subsequent calls (if any) to the move_io_space and destroy_io_space procedures.
The device is to make sure that any additional I/O space created by the CHARON core on
behalf of the device is destroyed with the destroy_io_space procedure (see below). The
suggested behavior is to create additional I/O spaces (if necessary) when processing a
bus power-up condition and destroy it when processing a bus power-down condition (see
below).
4.4 Destroying I/O space
The operation of destroying (additional) I/O space belongs to the class of operations
previously called “Access to device control and status registers”. Such an operation is
initiated by the device instance. The CHARON core is defined as a target of the operation.