pdc —
Processor-Dependent Code firmware driver
The pdc driver provides system console services through
  the PDC and also a means for calling PDC procedures, described later. The PDC
  console is used early in the kernel startup before enough kernel subsystems
  have been initialized to directly use the hardware i.e. serial ports,
  keyboard, and video.
The PDC version displayed at system boot is relevant to the
    particular system model and is not necessarily comparable to PDC versions on
    other systems.
PDC procedure calls are all made through a single entry point and assume normal
  C language calling conventions, with option number in the first argument and
  the return data address in the second, unless indicated otherwise. Each call
  requires at most 7KB of the available stack. Here is the list of procedures
  and options descriptions:
  - pdc(PDC_ADD_VALID,
    PDC_ADD_VALID_DFLT, paddr)
- Perform a read operation attempt at the physical address
      paddr without causing a HPMC, in order to verify
      that the address is valid and there is a device to respond to it. The
      implementation may choose to call the caller's HPMC handler and raise
      error conditions on the bus convertors.
- pdc(PDC_ALLOC,
    PDC_ALLOC_DFLT, ptr,
    size)
- Allocate static storage for IODC use of size bytes
      and return the address in a word pointed to by the
      ptr argument. There is no way of freeing the storage
      allocated and thus care shall be taken to not exhaust the total allocation
      limit of 32KB.
- pdc(PDC_BLOCK_TLB,
    PDC_BTLB_DEFAULT, ptr)
- Get block TLB parameters into the data area pointed to by the
      ptr argument. This includes minimal and maximal
      entry size and number of fixed and variable sized entries in the block
      TLB. Fixed entries have size of power of two and are aligned to the size
      where variable entries can have any size and base address both aligned to
      a page.
- pdc(PDC_BLOCK_TLB,
    PDC_BTLB_INSERT, sp,
    va, pa,
    len, acc,
    slot)
- Insert block TLB entry specified by the space ID sp,
      virtual address va, physical address
      pa, region length len, access
      rights acc, into the slot number
      slot.
- pdc(PDC_BLOCK_TLB,
    PDC_BTLB_PURGE, sp,
    va, slot,
    len)
- Purge one entry from the block TLB specified by the space ID
      sp, virtual address va, region
      length len, from slot number
      slot.
- pdc(PDC_BLOCK_TLB,
    PDC_BTLB_PURGE_ALL)
- Purge all entries from the block TLB.
- pdc(PDC_CACHE,
    PDC_CACHE_DFLT, ptr)
- Retrieve cache and TLB configuration parameters into the data area pointed
      to by the ptr argument. The format of the data
      stores is as follows:
    
      
        | addr | contents |  
        | 0x00 | I-cache size in bytes |  
        | 0x04 | I-cache configuration |  
        | 0x08 | I-cache base for flushing |  
        | 0x0c | I-cache stride for flushing |  
        | 0x10 | I-cache count for flushing |  
        | 0x14 | I-cache loop size for flushing |  
        | 0x18 | D-cache size in bytes |  
        | 0x1c | D-cache configuration |  
        | 0x20 | D-cache base for flushing |  
        | 0x24 | D-cache stride for flushing |  
        | 0x28 | D-cache count for flushing |  
        | 0x2c | D-cache loop size for flushing |  
        | 0x30 | ITLB size |  
        | 0x34 | ITLB configuration |  
        | 0x38 | ITLB space base for flushing |  
        | 0x3c | ITLB space stride for flushing |  
        | 0x40 | ITLB space count for flushing |  
        | 0x44 | ITLB address base for flushing |  
        | 0x48 | ITLB address stride for flushing |  
        | 0x4c | ITLB address count for flushing |  
        | 0x50 | ITLB loop size for flushing |  
        | 0x54 | DTLB size |  
        | 0x58 | DTLB configuration |  
        | 0x5c | DTLB space base for flushing |  
        | 0x60 | DTLB space stride for flushing |  
        | 0x64 | DTLB space count for flushing |  
        | 0x68 | DTLB address base for flushing |  
        | 0x6c | DTLB address stride for flushing |  
        | 0x70 | DTLB address count for flushing |  
        | 0x74 | DTLB loop size for flushing |  
 The cache configuration word is formatted as follows: 
      
        | bit | len | contents |  
        | 0 | 12 | reserved |  
        | 13 | 3 | set 1 if coherent operation supported |  
        | 16 | 2 | flush mode: 0 -- fdc & fic; 1 -- fdc; 2 -- fic; 3 -- either |  
        | 18 | 1 | write-thru D-cache if set |  
        | 19 | 2 | reserved |  
        | 21 | 3 | cache line size |  
        | 24 | 4 | associativity |  
        | 28 | 4 | virtual address alias boundary |  
 
- pdc(PDC_CACHE,
    PDC_CACHE_SETCS, ptr,
    i_cst, d_cst,
    it_cst, dt_cst)
- The second word in each of the i_cst,
      d_cst, it_cst, and
      dt_cst arguments specifies the desired coherency
      operation for the instructions cache, data cache, instructions TLB, and
      data TLB, respectively. The data area pointed to by the
      ptr argument receives the actual coherent operation
      state after an attempted change. The CPU does not support the requested
      operation change should the corresponding words not match the arguments
      upon return. The currently supported values are zero for incoherent
      operation, and one for coherent operation.
- pdc(PDC_CACHE,
    PDC_CACHE_GETSPIDB, ptr)
- The word pointed to by the ptr argument receives a
      mask of space ID used in hashing for cache tag.
- pdc(PDC_CHASSIS,
    PDC_CHASSIS_DISP, display)
- Update the chassis display with data given in the
      display argument. The bitfields in the word are as
      follows:
    
    
      - 0xe0000
- Specifies the system state.
        
          - 0x00000
- off
- 0x20000
- fault
- 0x40000
- test
- 0x60000
- initialize
- 0x80000
- shutdown
- 0xa0000
- warning
- 0xc0000
- run
- 0xe0000
- all on
 
- 0x10000
- Blank the chassis display.
- 0x0f000
- This and the other lower three nibbles specify the four hex digits to
          be displayed on the chassis display.
 
- pdc(PDC_CHASSIS,
    PDC_CHASSIS_WARN, ptr)
- Return the warnings from the chassis fans, temperature sensors, batteries
      and power supplies. A word of data is returned in the area pointed by the
      ptr argument and is described with bitfields:
    
    
      - 0xff000000
- Zero means none of the redundant chassis components has indicated any
          failures. A non-zero value specifies the failing component.
- 0x4
- Indicates the chassis battery charge is low.
- 0x2
- The chassis temperature has exceeded the low threshold.
- 0x1
- The chassis temperature has exceeded the middle threshold.
 
- pdc(PDC_CHASSIS,
    PDC_CHASSIS_ALL, ptr,
    display)
- Both retrieves the chassis warnings into the word pointed by the
      ptr argument and sets the chassis display using data
      in the display argument.
- pdc(PDC_COPROC,
    PDC_COPROC_DFLT, ptr)
- Identify the coprocessors attached to the CPU. The
      ptr points to a memory location where data is to be
      stored. The first word provides a mask for functional coprocessors and the
      second word is the mask for all present coprocessors.
- pdc(PDC_DEBUG,
    PDC_DEBUG_DFLT, ptr)
- Retrieve address of the PDC debugger placed in to the word pointed to by
      the ptr argument.
- pdc(PDC_IODC,
    PDC_IODC_READ, ptr,
    hpa, entry,
    addr, count)
- Given a module hpa, retrieve the specified
      entry from the module's IODC into a memory area at
      adr of count bytes long at
      most. The entry index is a one-byte index, with a
      value of zero being a special case. For the 0th entry, an IODC header of
      16 bytes is returned instead of an actual code.
- pdc(PDC_IODC,
    PDC_IODC_NINIT, ptr,
    hpa, spa)
- Non-destructively initialize the memory module specified by the
      hpa and spa arguments and
      return the module status after the init in the first word pointed to by
      the ptr argument, followed by the SPA space size and
      an amount of available memory bytes in the subsequent two words.
- pdc(PDC_IODC,
    PDC_IODC_DINIT, ptr,
    hpa, spa)
- Same as PDC_IODC_NINITexcept a destructive memory
      test is performed.
- pdc(PDC_IODC,
    PDC_IODC_MEMERR, ptr,
    hpa, spa)
- For the memory module that is specified by hpa and
      spa, return the last most severe error information
      comprised of copies of IO_STATUS, IO_ERR_RESP, IO_ERR_INFO, and IO_ERR_REQ
      registers placed into the data area pointed to by the
      ptr argument, and clear the error status.
- pdc(PDC_IODC,
    PDC_IODC_IMEMMASTER, ptr,
    hpa)
- HPA for the primary memory module is returned in a word pointed to by the
      ptr argument for a memory module specified by
      hpa if it's configured as a slave module in an
      interleave group.
- pdc(PDC_LAN_STATION_ID,
    PDC_LAN_STATION_ID_READ, macptr,
    hpa)
- Retrieve the MAC address for the device at hpa into
      the data area pointed to by the macptr
    argument.
- pdc(PDC_MEMMAP,
    PDC_MEMMAP_HPA., ptr,
    path)
- Returns device HPA in the word pointed to by the ptr
      argument given the device path pointer.
- pdc(PDC_MODEL,
    PDC_MODEL_INFO, ptr)
- Returns the System model numbers.
- pdc(PDC_MODEL,
    PDC_MODEL_BOOTID, boot_id)
- Set BOOT_ID of the processor module (used during boot process of monarch
      selection) to a word given in the boot_id
    argument.
- pdc(PDC_MODEL,
    PDC_MODEL_COMP, ptr,
    index)
- Retrieve processor component versions by issuing this procedure with
      subsequent indexes in the index argument starting at
      zero. The component version number is stored in the word pointed to by the
      ptr argument.
- pdc(PDC_MODEL,
    PDC_MODEL_MODEL, ptr,
    os_id, mod_addr)
- Return a string of 80 chars maximum stored at address
      mod_addr and conforming to the OS specified by the
      os_id 16-bit integer (see
      PDC_STABLEfor more information on OS ID). A word
      at the ptr address receives the result string
      length.
- pdc(PDC_MODEL,
    PDC_MODEL_CPUID, ptr)
- Retrieve CPU model information. A word stored at the address given by the
      ptr argument specifies the CPU revision in the lower
      5 bits followed by 7 bits of CPU model number.
- pdc(PDC_MODEL,
    PDC_MODEL_CPBALITIES, ptr)
- Retrieve platform capabilities into the word pointed by the
      ptr argument. Bit 0 and 1 specify that a 64- or
      32-bit OS is supported, respectively.
- pdc(PDC_MODEL,
    PDC_MODEL_GETBOOTOPTS, ptr)
- Retrieve the currently enabled, overall supported, and enabled by default
      boot test masks respectively stored at location pointed to by the
      ptr argument.
- pdc(PDC_MODEL,
    PDC_MODEL_SETBOOTOPTS, ptr,
    disable, enable)
- Disable boot tests specified by mask in the disable
      argument and enable boot tests specified by the mask given in the
      enable argument. The memory location pointed to by
      ptr will contain the resulting masks as returned by
      the PDC_MODEL_GETBOOTOPTS function. If an attempt is made to enable and
      disable the same test in one call a PDC_ERR_INVAL will be returned.
- pdc(PDC_NVM,
    PDC_NVM_READ, offset,
    ptr, count)
- Read contents of the NVM at offset into the memory
      area pointed to by the ptr argument of no more than
      count bytes.
    The format of the NVM is as follows: 
      
        | offset | size | contents |  
        | 0x00 | 0x24 | HV dependent |  
        | 0x24 | 0x20 | bootpath |  
        | 0x44 | 0x04 | ISL revision |  
        | 0x48 | 0x04 | timestamp |  
        | 0x4c | 0x30 | LIF utility entries |  
        | 0x7c | 0x04 | entry point |  
        | 0x80 | 0x80 | OS panic information |  
 
- pdc(PDC_NVM,
    PDC_NVM_WRITE, offset,
    ptr, count)
- Write data pointed to by the ptr argument of
      count bytes at address in the
      NVM.
- pdc(PDC_NVM,
    PDC_NVM_SIZE, ptr)
- Put the size of Non-Volatile Memory into the word pointed to by the
      ptr argument.
- pdc(PDC_NVM,
    PDC_NVM_VRFY)
- Verify that the contents of NVM are valid.
- pdc(PDC_NVM,
    PDC_NVM_INIT)
- Reset the contents of NVM to zeroes without any arguments.
- pdc(PDC_HPA,
    PDC_HPA_DFLT, ptr)
- The data returned provides the monarch CPUs HPA in the word pointed to by
      ptr.
- pdc(PDC_HPA,
    PDC_HPA_MODULES, ptr)
- Retrieve the bit mask for devices on the CPU bus into the data location
      pointed to by ptr. The first word is a bitmask for
      devices 0-31, and the second is a bitmask for devices 32-63, where bits
      set to one specify that the corresponding device number is on the same bus
      as the CPU.
- pdc(PDC_PIM,
    PDC_PIM_HPMC, offset,
    ptr, count)
- Get HPMC data from offset in Processor Internal
      Memory (PIM) into a ptr memory area of no more than
      count bytes in size. Data provided includes (in the
      order it is copied into the buffer): general registers (r0-r31), control
      registers (cr0-cr31), space registers (sr0-sr7), IIA space tail, IIA
      offset tail, check type, CPU state, cache check, TLB check, bus check,
      assist check, assist state, path info, system responder address, system
      requestor address, FPU registers (fpr0-fpr31).
- pdc(PDC_PIM,
    PDC_PIM_SIZE, ptr)
- Return the amount of data available in bytes in the word pointed to by
      ptr.
- pdc(PDC_PIM,
    PDC_PIM_LPMC, offset,
    ptr, count)
- Get LPMC data from offset in PIM into a
      ptr memory area of no more than
      count bytes in size. Data provided includes: HV
      dependent 0x4a words, check type, HV dependent word, cache check, TLB
      check, bus check, assist check, assist state, path info, system responder
      address, system requestor address, FPU registers (fpr0-fpr31).
- pdc(PDC_PIM,
    PDC_PIM_SBD, offset,
    ptr, count)
- Get Soft Boot Data from offset in PIM into a
      ptr memory area of no more than
      count bytes in size. Data provided includes: general
      registers (r0-r31), control registers (cr0-cr31), space registers
      (sr0-sr7), IIA space tail, IIA offset tail, HV dependent word, CPU
    state.
- pdc(PDC_PIM,
    PDC_PIM_TOC, offset,
    ptr, count)
- Get TOC (Transfer Of Control) data from offset in
      PIM into a ptr memory area of no more than
      count bytes in size. Data provided includes: general
      registers (r0-r31), control registers (cr0-cr31), space registers
      (sr0-sr7), IIA space tail, IIA offset tail, HV dependent word, CPU
    state.
- pdc(PDC_POW_FAIL,
    PDC_POW_FAIL_DFLT)
- Prepare for power fail. On the machines that provide power failure
      interrupts, this function is to be called after the operating system has
      completed shutdown(8)
      to finish system-dependent tasks and power down. This function only
      requires 512 bytes of stack.
- pdc(PDC_PROC,
    PDC_PROC_STOP)
- Stop the currently executing processor and also disable bus requestorship,
      disable interrupts, and exclude the processor from cache coherency
      protocols. The caller must flush any necessary data from the cache before
      calling this function.
- pdc(PDC_PROC,
    PDC_PROC_RENDEZVOUS)
- Enter the reset rendezvous code on the current processor. This function is
      only implemented on category B processors and implementation is optional
      on category A processors.
- pdc(PDC_PSW,
    PDC_PSW_GETMASK, ptr)
- Get the mask of default bits implemented into a word pointed to by the
      ptr argument. The following mask values are
      possible:
    
    
      - 1
- Default endianness bit is available.
- 2
- Default word width bit is available.
 
- pdc(PDC_PSW,
    PDC_PSW_DEFAULTS, ptr)
- Retrieve the default PSW bits into the word pointed to by the
      ptr argument.
- pdc(PDC_PSW,
    PDC_PSW_SETDEFAULTS, bits)
- Set the default PSW bits.
- pdc(PDC_SOFT_POWER,
    PDC_SOFT_POWER_INFO, ptr)
- Retrieve “power” register address into the word pointed to
      by the ptr argument. Bit-0 in the
      “power” register address being set specifies the power
      button being depressed. No dampening is required, unlike with the
      hppa/lasi(4) power
      circuit.
- pdc(PDC_SOFT_POWER,
    PDC_SOFT_POWER_ENABLE, ptr,
    stat)
- Enable (zero stat) or disable (non-zero
      stat) the soft power function, where disable means
      the machine will turn immediately off should the power get depressed. The
      ptr argument still points to the data provided
      previously by the PDC_SOFT_POWER_INFO call.
- pdc(PDC_STABLE,
    PDC_STABLE_READ, offset,
    ptr, count)
- Read contents of the “Stable Storage” at
      offset into the memory area pointed to by the
      ptr argument of no more than
      count bytes.
    The format of the stable storage is as follows: 
      
        | offset | size | contents |  
        | 0x0000 | 0x20 | primary bootpath |  
        | 0x0020 | 0x20 | reserved |  
        | 0x0040 | 0x02 | OS ID |  
        | 0x0042 | 0x16 | OS dependent |  
        | 0x0058 | 0x02 | diagnostic |  
        | 0x005a | 0x03 | reserved |  
        | 0x005d | 0x02 | OS dependent |  
        | 0x005f | 0x01 | fast size |  
        | 0x0060 | 0x20 | console path |  
        | 0x0080 | 0x20 | alternative boot path |  
        | 0x00a0 | 0x20 | keyboard path |  
        | 0x00c0 | 0x20 | reserved |  
        | 0x00e0 | size | OS dependent |  
 The “OS ID” field may have the following
      values: 
      
        | value | OS |  
        | 0x000 | No OS-dependent info |  
        | 0x001 | HP-UX |  
        | 0x002 | MPE-iX |  
        | 0x003 | OSF |  
        | 0x004 | HP-RT |  
        | 0x005 | Novell Netware |  
 The “fast size” field is the amount of memory to
        be tested upon system boot and is a power of two multiplier for 256KB.
        Values of 0xe and 0xf are reserved. 
- pdc(PDC_STABLE,
    PDC_STABLE_WRITE, address,
    ptr, count)
- Write data pointed to by the ptr argument of
      count bytes at address in the
      “Stable Storage”.
- pdc(PDC_STABLE,
    PDC_STABLE_SIZE, ptr)
- Put the size of the “Stable Storage” into the word pointed
      to by the ptr argument.
- pdc(PDC_STABLE,
    PDC_STABLE_VRFY, ptr)
- Verify that the contents of the “Stable Storage” are
    valid.
- pdc(PDC_STABLE,
    PDC_STABLE_INIT, ptr)
- Reset the contents of the “Stable Storage” to zeroes.
- pdc(PDC_SYSMAP,
    PDC_SYSMAP_FIND, ptr,
    path, number)
- Map module number into HPA and also provide an area
      size starting at HPA and a number of additional addresses placed into the
      data area pointed to by the ptr argument words one,
      two, and three, respectively. The device path is placed into the data area
      pointed to by the path argument.
- pdc(PDC_SYSMAP,
    PDC_SYSMAP_ADDR, ptr,
    im, ia)
- Retrieve a list of additional addresses for the module number
      im for the address index ia.
      The result is placed into the data area pointed to by
      ptr, where the first word gives the address and the
      second the size of the area.
- pdc(PDC_SYSMAP,
    PDC_SYSMAP_HPA, ptr,
    path_ptr)
- Map device path_ptr into device's HPA placed into a
      word pointed to by the ptr argument.
- pdc(PDC_TLB,
    PDC_TLB_INFO, ptr)
- Retrieve the hardware TLB handler parameters. This includes a minimal and
      maximal size for the page table, in bytes, stored into words zero and one,
      respectively, in the data area pointed to by the ptr
      argument.
- pdc(PDC_TLB,
    PDC_TLB_CONFIG, ptr,
    base, size,
    param)
- Configure the hardware TLB miss handler given the same parameters fetched
      previously with PDC_TLB_INFO into data area pointed to by the
      ptr and page table base
      address, page table size, and handler parameters
      param. The hardware TLB handler parameter bits are
      as follows:
    
    
      - 1
- Enable the hardware TLB miss handler. The default is to load cr28 with
          the faulted page table entry address.
- 4
- Pointer to the next page table entry is put into cr28.
- 6
- Next pointer field of the page table entry is put into cr28.
 Resetting the page table address and/or size without disabling
        the hardware TLB miss handler is allowed. Any changes made are immediate
        upon Code or Data virtual address translation bits are set in PSW. 
- pdc(PDC_TOD,
    PDC_TOD_READ, ptr)
- Read the TOD, which is a UNIX Epoch time, into the data area pointed to by
      the ptr argument. That includes seconds in the first
      word and microseconds in the second.
- pdc(PDC_TOD,
    PDC_TOD_WRITE, sec,
    usec)
- Write TOD with UNIX Epoch time with sec seconds and
      usec microseconds.
- pdc(PDC_TOD,
    PDC_TOD_ITIMER, ptr)
- Get TOD and CPU timer accuracy into the data location pointed to by the
      ptr argument. The first two words specify a double
      floating-point value giving CPU timer frequency. The next two words
      provide accuracy in parts per billion for the TOD and CPU timer,
      respectively.
  - machine/pdc.h
- C header file with relevant definitions.
- /sys/arch/hppa/dev/cpudevs
- System components' version numbers.
- /dev/console
- System console device.
Upon successful completion all procedures return zero. The following error codes
  are returned in case of failures:
  - PDC_ERR_NOPROC
- No such procedure
- PDC_ERR_NOPT
- No such option
- PDC_ERR_COMPL
- Unable to complete without error
- PDC_ERR_EOD
- No such device
- PDC_ERR_INVAL
- Invalid argument
- PDC_ERR_PFAIL
- Aborted by powerfail
hppa/intro(4),
  hppa/io(4),
  hppa/lasi(4)Hewlett-Packard,
    PA-RISC 1.1 Firmware Architecture Reference
    Specification, March 8, 1999.
Hewlett-Packard,
    PA-RISC 2.0 Firmware Architecture Reference
    Specification, March 7, 1999.