os_set_msparam(D3psm)

Synopsis

   void os_set_msparam(msparam_t msparam, void *valuep)

Description

os_set_msparam can be called only from the PSM's initpsm entry point. These parameters, therefore, cannot be changed once the PSM is initialized. os_set_msparam must not be called more than once for the same parameter from the same initpsm operation.

The PSM should set the following machine-specific parameters by calling os_set_msparam from the initpsm function. If the PSM does not set a parameter, the default value is used.

The following table lists the parameter numbers:

Parameter	msparam value
MSPARAM_PLATFORM_NAME	1
MSPARAM_SW_SYSDUMP	2
MSPARAM_TIME_RES	3
MSPARAM_TICK_1_RES	4
MSPARAM_TICK_1_MAX	5
MSPARAM_TICK_2_RES	6
MSPARAM_TICK_2_MAX	7
MSPARAM_ISLOT_MAX	8
MSPARAM_INTR_ORDER_MAX	9
MSPARAM_INTR_TASKPRI_MAX	10
MSPARAM_SHUTDOWN_CAPS	11
MSPARAM_TOPOLOGY	12
MSPARAM_FARCOPY_MIN	15
MSPARAM_HW_SERIAL	16

 Parameter                  msparam value
 MSPARAM_PLATFORM_NAME      1
 MSPARAM_SW_SYSDUMP         2
 MSPARAM_TIME_RES           3
 MSPARAM_TICK_1_RES         4
 MSPARAM_TICK_1_MAX         5
 MSPARAM_TICK_2_RES         6
 MSPARAM_TICK_2_MAX         7
 MSPARAM_ISLOT_MAX          8
 MSPARAM_INTR_ORDER_MAX     9
 MSPARAM_INTR_TASKPRI_MAX   10
 MSPARAM_SHUTDOWN_CAPS      11
 MSPARAM_TOPOLOGY           12
 MSPARAM_FARCOPY_MIN        15
 MSPARAM_HW_SERIAL          16

MSPARAM_PLATFORM_NAME(char *)

Descriptive name for the platform. This will usually include the name of the vendor and the name of the particular hardware platform product or product line. The string may include spaces, for example, ``XYZCorp SuperSys''. The PSM may provide different values depending on the actual platform that is detected. This parameter is optional, with a default value of ``(unknown)''.

---

NOTE: This string is used to provide the value for SI_HW_PROVIDER. For PSMs that cannot determine a specific hardware vendor, the string ``Generic'' should be used, for example: ``Generic AT'' or ``Generic MP''.

---

MSPARAM_HW_SERIAL(char )

The serial number for the particular instance of platform hardware on which the system is running. This parameter should be set only if the PSM is able to determine the number and be sure that it is reasonably unique amongst systems with the same platform name. Uniqueness is not required.

---

NOTE: On many platforms, the PSM will be unable to determine a serial number.

---

MSPARAM_SW_SYSDUMP(ms_bool_t)

Set to MS_TRUE if system crash dumps are to be implemented by the core kernel on the way down. Defaults to MS_TRUE.

MSPARAM_TIME_RES(ms_time_t)

The resolution (that is, the minimum increment) of the free-running clock counter, as read by MSOP_TIME_GET(D2psm) and MSOP_TIME_CVT(D2psm).

MSPARAM_TICK_1_RES(ms_time_t)

The resolution (that is, the minimum increment) of the first heartbeat clock tick interrupt (clock 1). This may or may not be the same value as MSPARAM_TIME_RES.

MSPARAM_TICK_1_MAX(ms_time_t)

The maximum period of the first heartbeat clock tick interrupt (clock 1). When the core kernel specifies its desired heartbeat period via os_tick_period, it must not use a value greater than MSPARAM_TICK_1_MAX.

MSPARAM_TICK_2_RES(ms_time_t)

The resolution (that is, the minimum increment) of the second heartbeat clock tick interrupt (clock 2). This may or may not be the same value as MSPARAM_TIME_RES.

Set this parameter only if clock 2 is programmable separately from clock 1.

MSPARAM_TICK_2_MAX(ms_time_t)

The maximum period of the second heartbeat clock tick interrupt (clock 2). When the core kernel passed its desired heartbeat period to MSOP_TICK_2(D2psm), it must not use a value greater than MSPARAM_TICK_2_MAX.

Set this parameter only if clock 2 is programmable separately from clock 1.

MSPARAM_ISLOT_MAX(ms_islot_t)

The maximum (inclusive) interrupt slot number supported by the PSM. This lets the core kernel allocate arrays indexed by interrupt slot number if it so chooses.

MSPARAM_INTR_ORDER_MAX(unsigned int)

The maximum (inclusive) interrupt order number supported by the PSM. Defaults to zero, which indicates that the PSM does not support ordered masking. The PSM should support only ordered masking if the interrupt circuitry that it controls supports ordered masking efficiently. For information about ordered masking, see MSOP_INTR_ATTACH(D2psm) and MSOP_INTR_COMPLETE(D2psm).

MSPARAM_INTR_TASKPRI_MAX(unsigned int)

The maximum (inclusive) interrupt task priority supported by the PSM. Defaults to zero. See MSOP_INTR_TASKPRI(D2psm).

MSPARAM_FARCOPY_MIN(ms_size_t)

The minimum (inclusive) size in bytes, for which the accelerated copy function MSOP_FARCOPY(D2psm) should be used (if it is registered).

MSPARAM_SHUTDOWN_CAPS(unsigned int)

Supported shutdown capabilities. MSPARAM_SHUTDOWN_CAPS is a bitmask of the values for the action parameter of MSOP_SHUTDOWN(D2psm) which indicate the set of actions performed by the hardware platform.

Defaults to zero.

MSPARAM_TOPOLOGY(ms_topology_t *)

A pointer to the structure ms_topology_t that describes the platform hardware topology, for example, its memory layout, primary I/O buses and similar.

Resource topology structure

The PSM creates a topology structure either statically or during a call to initpsm, and sets MSPARAM_TOPOLOGY to be a pointer to this structure. The PSM can base this topology structure in whole or in part on os_default_topology, the topology determined by the core kernel as best it can, without platform-specific knowledge.

The basic topology structure is as follows:

   typedef struct {
      unsigned int mst_nresource;
      ms_resource_t *mst_resources;
   } ms_topology_t;

Each resource is described by an ms_resource_t structure, and is included in an array of such structures, pointed to by mst_resources. The ms_resource_t structure is as follows:

   typedef struct {
      ms_cgnum_t msr_cgif;          /* Nearest CPU group */
      ms_bool_t msr_private;        /* True if resource is private
                                       (cannot be accessed from
                                        other CPU groups) */
      ms_cpu_t msr_private_cpu;     /* MS_CPU_ANY or CPU #
                                       resource restricted to */
      msr_type_t msr_type;          /* Type of resource */
   

      union {
         msr_cpu_t msr_cpu;
         msr_cache_t msr_cache;
         msr_memory_t msr_memory;
         msr_bus_t msr_bus;
         msr_cg_t msr_cg;
      } msri;
   } ms_resource_t;

msr_type	msr_type number	Variable	Description
MSR_CPU	1	msr_cpu	A CPU
MSR_ICACHE	2	msr_cache	An instruction-only cache
MSR_DCACHE	3	msr_cache	A data-only cache
MSR_UCACHE	4	msr_cache	A unified cache
MSR_BUS	5	msr_bus	An I/O bus bridge
MSR_MEMORY	6	msr_memory	Mainstore memory
MSR_CG	7	msr_cg	A CPU group

 +-----------+-----------------+------------+---------------------------+
 |msr_type   | msr_type number | Variable   | Description               |
 +-----------+-----------------+------------+---------------------------+
 |MSR_CPU    | 1               | msr_cpu    | A CPU                     |
 +-----------+-----------------+------------+---------------------------+
 |MSR_ICACHE | 2               | msr_cache  | An instruction-only cache |
 +-----------+-----------------+------------+---------------------------+
 |MSR_DCACHE | 3               | msr_cache  | A data-only cache         |
 +-----------+-----------------+------------+---------------------------+
 |MSR_UCACHE | 4               | msr_cache  | A unified cache           |
 +-----------+-----------------+------------+---------------------------+
 |MSR_BUS    | 5               | msr_bus    | An I/O bus bridge         |
 +-----------+-----------------+------------+---------------------------+
 |MSR_MEMORY | 6               | msr_memory | Mainstore memory          |
 +-----------+-----------------+------------+---------------------------+
 |MSR_CG     | 7               | msr_cg     | A CPU group               |
 +-----------+-----------------+------------+---------------------------+

Resources near a particular CPU group (as indicated by msr_cgnum) are also accessible from other CPU groups, but with a higher latency cost, unless the msr_private flag is set.

msr_private_cpu is valid only if the msr_private flag is set. In this case, if msr_private_cpu is not equal to MS_CPU_ANY, it is the CPU number of the one CPU that can access the resource.
Type-specific resource information is described in the following structures:

   typedef struct {
      ms_cpu_t msr_cpuid;           /* CPU number */
      unsigned long msr_clockspeed;  /* CPU clock frequency
                                       (zero if not known) */
   } msr_cpu_t;
   

   typedef struct {
      ms_memsize_t msr_size;        /* Total cache size, in bytes */
      ms_size_t msr_line_size;      /* Cache line size, in bytes */
      unsigned long msr_level;      /* Level in cache hierarchy
                                      (1 is closest to CPU) */
      unsigned long msr_associativity;
      ms_bool_t msr_dma_coherent;
      ms_bool_t msr_write_through;
      ms_bool_t msr_far_only;
      ms_bool_t msr_read_only;
   } msr_cache_t;
   

   typedef struct {
      ms_paddr_t msr_address;
      ms_memsize_t msr_size;
      unsigned int msr_flags;
   } msr_memory_t;
   

   typedef struct {
      msr_bus_type_t msr_bus_type;
      unsigned long msr_bus_number;
      msr_routing_t *msr_intr_routing;
      unsigned int msr_n_routing;
   } msr_bus_t;
   

   typedef struct {
      ms_cgid_t msr_cgid;
   } msr_cg_t;

MSR_RESERVED (1 << 0)

This memory is reserved and should not be used.

The msr_bus_type field of an msr_bus_t structure identifies the type of I/O bus. It can take the following values:

msr_bus_type	msr_bus_type number
MSR_BUS_NONSTD	0
MSR_BUS_PCI	1
MSR_BUS_EISA	2
MSR_BUS_MCA	3
MSR_BUS_ISA	4

 msr_bus_type     msr_bus_type number
 MSR_BUS_NONSTD   0
 MSR_BUS_PCI      1
 MSR_BUS_EISA     2
 MSR_BUS_MCA      3
 MSR_BUS_ISA      4

msr_intr_routing_t describes the interrupt routing (mapping from interrupt sources to interrupt slots). If set to NULL, the standard routing for the bus type will be used. Standard routing for ISA, EISA and MCA is one-to-one (that is, IRQ, interrupt source and interrupt slot are identical). Standard routing for PCI is determined by calling the PCI BIOS. If msr_intr_routing_t is not NULL, it points to an array of msr_n_routing entries with the following structure:

   typedef struct {
      unsigned long msr_isource;
      ms_islot_t msr_islot;
   } msr_routing_t;

For ISA, EISA and MCA bus types, the interrupt source is the IRQ number. For the PCI bus type, the interrupt source is a tuple of (PCI bus #, device #, pin #), with the interrupt pin # (A=0, B=1, C=2, D=3) in the low 2 bits, the device # in the next 5 bits and the PCI bus # in the remaining bits.

Arguments

msparam

the number of the MSPARAM_

valuep

a generic pointer to the data structures to be passed

Return values

Usage

Hardware applicability

Version applicability

References