| /* |
| * (C) Copyright IBM Corp. 2007, 2010 |
| * |
| * This program is free software; you can redistribute it and/or modify it |
| * under the terms of the GNU General Public License as published by the |
| * Free Software Foundation; either version 2 of the License, or (at your |
| * option) any later version. |
| * |
| * This program is distributed in the hope that it will be useful, but |
| * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY |
| * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| * for more details. |
| * |
| * You should have received a copy of the GNU General Public License along |
| * with this program; if not, see <http://www.gnu.org/licenses>. |
| * |
| * Author: Tom Gooding, IBM |
| */ |
| |
| |
| #ifndef _BGCNS_H |
| #define _BGCNS_H |
| |
| |
| #ifndef __ASSEMBLY__ |
| |
| /*! @page CNS Common Node Services |
| * |
| * @section CNS_S10 Overview |
| * |
| * As the name implies, the <b>Common Node Services (CNS)</b> layer provides @b services |
| * to the kernel. These services may be simple queries abstracting various node |
| * specific data (such as DDR size) or they may be more sophisticated software services, |
| * such as common machine check handling. Additionally, some services may be implicit, |
| * such as the initialization of various hardware devices unique to Blue Gene, such as |
| * Netbus and SerDes. |
| * |
| * Services are not directly linked into the kernel, but rather are invoked from kernel |
| * code via a <b>service directory</b> which is itself part of an overall <b>service |
| * descriptor</b>. This service descriptor is constructed during initialization and |
| * is passed to the kernel when the kernel is booted. The service directory is a |
| * collection of <b>service references</b>. |
| * |
| * During partition (block) booting, ELF images are loaded onto the compute and I/O nodes. |
| * The bootloader (@i aka microloader) boots first and then transfers control to the Common |
| * Node Services layer so that it, in turn, may boot. |
| * |
| * Once the CNS layer has booted, control is transferred to the kernel so that it may also |
| * boot. All services provided by the CNS layer are immediately available at this time. |
| * |
| * @section CNS_S20 Programming Model |
| * |
| * A kernel running on top of the CNS layer is not statically linked to the common services. |
| * Instead, the services are called via function pointers provided by the services descriptor, |
| * which is described here: @ref _BGCNS_ServiceDirectory. |
| * |
| * The kernel must operate under the following rules and restrictions: |
| * @li The kernel must not alter the services descriptor. The descriptor must be treated as a read-only |
| * data structure even though the kernel may have the ability to alter it. Because CNS trusts the |
| * kernel, this also implies that the kernel must not expose the descriptor to any untrusted |
| * software (such as application code). |
| * @li The kernel must ensure that the CNS virtual memory region is mapped prior to invoking any |
| * service. |
| * @li The kernel must ensure that any data passed to services via parameters is mapped. |
| * Specifically, TLB entries must be mapped as shared (TID = 0) and must be either readable |
| * (input parameters) or readable and writeable (output parameters). |
| * @li The kernel must treat the virtual address range (@ref _BGCNS_Descriptor::baseVirtualAddress , |
| * _BGCNS_Descriptor::baseVirtualAddress + @ref _BGCNS_Descriptor::size - 1) as reserved. |
| * That is, the kernel must not use this region of virtual memory for anything besides accessing |
| * the services descriptor. |
| * @li The kernel must treat the physical address range (@ref _BGCNS_Descriptor::basePhysicalAddress, |
| * _BGCNS_Descriptor::basePhysicalAddress + _BGCNS_Descriptor::size - 1) as reserved. The |
| * kernel must not map this memory for any other use. |
| * @li The kernel must not access any of the reserved virtual address regions with TLB settings that |
| * are different from those used by CNS. The kernel is allowed to unmap any of the reserved |
| * memory TLBs for its own use. However, in such a case and per the rule above, the kernel must |
| * ensure that the region is mapped prior to using any CNS facilities (such as invoking a service). |
| * @li CNS may need to map one or more TLB entries in order to access Blue Gene devices. In such a case, |
| * CNS may borrow TLB entries; the TLB will be returned to its original state before the service returns |
| * control to the invoking kernel. Kernels may avoid this behavior for specific devices by using |
| * the mapDevice service. |
| * @li The kernel's ELF image must avoid the 256K region of memory between 0x07000000 and 0x0703FFFF. This |
| * region is used for the pre-relocated CNS image and will be available for general use once CNS boot |
| * is complete. |
| * @li The kernel must not alter any reserved SPRs, DCRs or memory-mapped device registers. |
| * |
| * The CNS software may behave unpredictably if any of these rules and restrictions is violated. |
| * |
| * Kernels may make the following assumptions about CNS: |
| * |
| * @li The data passed in the firmware descriptor (see below) is static. Specifically, the base addresses, |
| * size and service directory will not change once CNS boot is complete. |
| * |
| * @subsection CNS_21 Programming Examples |
| * |
| * @subsubsection CNS_211 Obtaining the Personality |
| * |
| * The following example shows how to fetch a copy of the Blue Gene personality structure and also |
| * serves as a simple example of invoking a service: |
| * |
| * @code |
| * |
| * BGCNS_Descriptor* descr = ...; // obtained from CNS at boot time |
| * _BGP_Personality_t* pers = (_BGP_Personality_t*)(*descr->services->getPersonalityData)(); |
| * ... |
| * @endcode |
| * |
| * The programming model guarantees that the descriptor is static. Thus, one can provide a |
| * convenience method to make service invocation a little more readable |
| * |
| * @code |
| * |
| * |
| * static BGCNS_Descriptor* _cns_descriptor = ...; // obtained from CNS at boot time |
| * |
| * inline BGCNS_ServiceDirectory* cns() { return _cns_descriptor->services; } |
| * |
| * void foo() { |
| * _BGP_Personality_t* pers = (_BGP_Personality_t*)cns()->getPersonalityData(); |
| * ... |
| * } |
| * |
| * @endcode |
| * |
| * This style will be used in all of the subsequent examples. |
| * |
| * @subsubsection CNS_212 SMP Initialization |
| * |
| * Common Node Services will launch the kernel on a single core (typically core 0) and will |
| * leave the remaining cores parked. The kernel can activate additional cores via the @c takeCPU |
| * service. Here is a very simple example of such kernel code: |
| * |
| * @code |
| * |
| * void anEntryPoint(unsigned core, void* arg_not_used) { |
| * // Do whatever your kernel needs to do here. Typically, |
| * // this function never returns. You will arrive here |
| * // when takeCPU is invoked (below). |
| * } |
| * |
| * void someCodeOnTheMainThread() { |
| * |
| * // ... |
| * |
| * unsigned N = cns()->getNumberOfCores(); |
| * |
| * for (core = 1; core < N; core++) { |
| * if ( cns()->takeCPU(core, NULL, &anEntryPoint) != 0 ) { |
| * // error handling goes here |
| * } |
| * } |
| * |
| * // ... |
| * } |
| * |
| * @endcode |
| * |
| * @subsubsection CNS_213 Version Compatibility |
| * |
| * Common Node Services structures and APIs should remain compatible within maintenance |
| * releases and e-fixes. Kernel's may add a runtime check to ensure that the version |
| * of CNS is compatible with the version from compile time. This is done as follows: |
| * |
| * @code |
| * |
| * BGCNS_Descriptor* descr = ...; // obtained from CNS at boot time |
| * |
| * if ( ! BGCNS_IS_COMPATIBLE(descr) ) { |
| * // incompatible CNS (panic?) |
| * } |
| * |
| * @endcode |
| * |
| * @subsubsection CNS_23 Interrupts |
| * |
| * A kernel wanting to use the CNS interrupt services would first have to enable interrupts |
| * for the appropriate Blue Gene BIC group and IRQ within that group. This would likely be |
| * done at boot time. So, for example, such a kernel could enable interrupts for the Universal |
| * Performance Counter (group 5, IRQ 2) to be handled by the non-critical handler of core 0 as |
| * follows: |
| * |
| * @code |
| * cns()->enableInterrupt(5, 2, BGCNS_NonCritical, 0); |
| * @endcode |
| * |
| * Such a kernel might also maintain a collection of routines that act as subhandlers of the |
| * non-critical interrupt handler. In this example, we'll assume it is simply a two |
| * dimensional array indexed by group and IRQ: |
| * |
| * @code |
| * subhandlers[5][2] = &theUpcSubHandler; |
| * @endcode |
| * |
| * That kernel's non-critical interrupt handler would then typically handle all interrupts by |
| * successively invoking the getInterrupt() service to determine the group and IRQ, and then |
| * dispatching the appropriate subhandler. Additionally, the interrupt will be acknowledged |
| * so to avoid continuous interruption: |
| * |
| * @code |
| * unsigned grp, irq; |
| * |
| * while ( cns()->getInterrupt(&g, &i, BGCNS_NonCritical) == 0) { |
| * (*subhandlers[g][i])(); // dispatch the handler |
| * cns()->acknowledgeInterrupt(g,i); // ack the interrupt |
| * } |
| * @endcode |
| * |
| * @subsubsection CNS_24 Global Barriers and Interrupts |
| * |
| * The Blue Gene/P Global Interrupt Controller (aka GLINT) provides 4 independent channels |
| * that may be configured as either a global barrier or a global interrupt. |
| * |
| * Barriers are constructed by invoking the barrier service: |
| * |
| * @code |
| * unsigned channel = 0; |
| * |
| * // synchronize: |
| * int reset = 1; |
| * int rc; |
| * while ( (rc = cns()->globalBarrier_nonBlocking(channel, reset, 1000)) == BGCNS_RC_CONTINUE ) { |
| * reset = 0; |
| * } |
| * |
| * if ( rc == BGCNS_RC_COMPLETE ) { |
| * // good path |
| * } |
| * else { |
| * // error |
| * } |
| * @endcode |
| * |
| * Similarly, a barrier with a timeout can also be constructed: |
| * |
| * @code |
| * unsigned channel = 0; |
| * int reset = 1; |
| * unsigned long long startTime = ...; // obtain current time |
| * int rc; |
| * |
| * while ( (rc = cns()->globalBarrier_nonBlocking(channel,reset, 1000)) == BGCNS_RC_CONTINUE ) { |
| * reset = 0; |
| * unsigned long long currentTime = ...; // obtain current time |
| * if ( currentTime - startTime > timeout ) |
| * break; |
| * } |
| * |
| * if ( rc == BGCNS_RC_COMPLETE ) { |
| * // good path |
| * } |
| * else { |
| * // timeout or error |
| * } |
| * @endcode |
| * |
| * A node may opt out of a barrier channel via the disableBarrier service: |
| * |
| * @code |
| * |
| * // some other synchronization mechanism needs to go here |
| * |
| * cns()->disableBarrier(channel); |
| * |
| * @endcode |
| * |
| * Conversely, it may opt back in: |
| * |
| * @code |
| * cns()->enableBarrier(channel, user_mode); |
| * @endcode |
| * |
| * By default, CNS reserves the use of channel 2 as a global interrupt for environmental |
| * monitoring. It also reserves channel 3 for use as a supervisory mode, compute-node |
| * only barrier. Compute node kernels are free to share this channel for the same |
| * purpose (compute node, supervisory barrier). The enable/disable barrier services |
| * may return errors if operating on a reserved channel. |
| * |
| * NOTE: The standard BG/P software stack, which includes I/O node Linux and Compute Node |
| * Kernel (CNK) uses channel 0 as an I/O node barrier during boot and transforms it to an |
| * compute-node only barrier when jobs execute. |
| * |
| * |
| * @section CNS_3 DMA Services |
| * |
| * The DMA services provided in CNS are low-level services. Interested readers of this area should |
| * also look at the documentation for the DMA SPIs, which are at a slightly higher level. |
| * |
| * |
| * |
| * @section CNS_4 Reserved and Preferred Addresses |
| * |
| * |
| * The following virtual memory regions are reserved and must be avoided by |
| * kernels: |
| * |
| * @code |
| * |
| * +------------+------------+------+----------------------+-----------------------+ |
| * | Lower | Upper | Size | Usage | Attributes | |
| * +------------+------------+------+----------------------+-----------------------+ |
| * | CNSlow[1] | CNShigh[2] | 256K | CNS | I, Rs, Ws, Xs | |
| * +------------+------------+------+----------------------+-----------------------+ |
| * |
| * [1] CNSlow = descr->baseVirtualAddress , usually 0xFFF40000 |
| * [2] CNShigh = descr->baseVirtualAddress + descr->size - 1; usually 0xFFF7FFFF |
| * |
| * @endcode |
| * |
| * The following virtual memory regions are used by default in CNS. Kernels that wish to have |
| * a different memory map may do so via the mapDevice service. |
| * |
| * @code |
| * +------------+------------+------+----------------------+-----------------------+ |
| * | Lower | Upper | Size | Usage | Attributes | |
| * +------------+------------+------+----------------------+-----------------------+ |
| * | 0xFFFB0000 | 0xFFFCFFFF | 64K | Torus | I, G, Rs, Ws, Ru, Wu | |
| * +------------+------------+------+----------------------+-----------------------+ |
| * | 0xFFFD0000 | 0xFFFD3FFF | 16K | DMA | I, G, Rs, Ws, Ru, Wu | |
| * +------------+------------+------+----------------------+-----------------------+ |
| * | 0xFFFD9000 | 0xFFFD9FFF | 4K | DevBus | I, G, Rs, Ws | |
| * +------------+------------+------+----------------------+-----------------------+ |
| * | 0xFFFDA000 | 0xFFFDAFFF | 4K | UPC | I, G, Rs, Ws, Ru, Wu | |
| * +------------+------------+------+----------------------+-----------------------+ |
| * | 0xFFFDC000 | 0xFFFDD3FF | 4K | Collective | I, G, Rs, Ws, Ru, Wu | |
| * +------------+------------+------+----------------------+-----------------------+ |
| * | 0xFFFDE000 | 0xFFFDEFFF | 4K | BIC | I, G, Rs, Ws, Xs | |
| * +------------+------------+------+----------------------+-----------------------+ |
| * | 0xFFFF0000 | 0xFFFF3FFF | 16K | Lockbox (supervisor) | I, G, Rs, Ws | |
| * +------------+------------+------+----------------------+-----------------------+ |
| * | 0xFFFF4000 | 0xFFFF7FFF | 16K | Lockbox (user) | I, G, Rs, Ws, Ru, Wu | |
| * +------------+------------+------+----------------------+-----------------------+ |
| * | 0xFFFF8000 | 0xFFFFFFFF | 32K | SRAM | SWOA, WL1, Rs, Ws, Xs | |
| * +------------+------------+------+----------------------+-----------------------+ |
| * @endcode |
| * |
| */ |
| |
| |
| #define BGCNS_VERSION 0x01030000 /* V1R3M0 efix 0 */ |
| #define BGCNS_IS_COMPATIBLE(descr) ( ((descr)->version & 0xFFFF0000) == (BGCNS_VERSION & 0xFFFF0000) ) //!< True iff the given descriptor is compatible with this version of CNS |
| |
| /* ! @enum BGCNS_InterruptType */ |
| /* ! @brief Defines the different types of interrupts known to */ |
| /* ! Common Node Services. */ |
| typedef enum { |
| BGCNS_NonCritical, //!< Non-critical interrupt |
| BGCNS_Critical, //!< Critical interrupt |
| BGCNS_MachineCheck, //!< Machine check |
| } BGCNS_InterruptType; |
| |
| /* ! @enum BGCNS_FifoOperation */ |
| /* ! @brief Defines the types of FIFO operations */ |
| /* ! @see _BGCNS_ServiceDirectory::setDmaFifoControls */ |
| /* ! @see _BGCNS_ServiceDirectory::setDmaLocalCopies */ |
| /* ! @see _BGCNS_ServiceDirectory::setDmaPriority */ |
| typedef enum { |
| BGCNS_Disable = 0, |
| BGCNS_Enable = 1, |
| BGCNS_Reenable = 2 |
| } BGCNS_FifoOperation; |
| |
| /* ! @enum BGCNS_FifoFacility */ |
| /* ! @brief Defines the various types of FIFO facilities */ |
| typedef enum { |
| BGCNS_InjectionFifo, //!< Normal Injection FIFO |
| BGCNS_ReceptionFifo, //!< Normal Reception FIFO |
| BGCNS_ReceptionHeaderFifo, //!< Reception Header FIFO (typically used only for debugging) |
| BGCNS_InjectionFifoInterrupt, |
| BGCNS_ReceptionFifoInterrupt, |
| BGCNS_ReceptionHeaderFifoInterrupt, |
| BGCNS_InjectionCounterInterrupt, |
| BGCNS_ReceptionCounterInterrupt |
| } BGCNS_FifoFacility; |
| |
| /* ! @enum BGCNS_LinkType */ |
| /* ! @brief Defines the types of MAC links. */ |
| /* ! @see _BGCNS_ServiceDirectory::macTestLink */ |
| typedef enum { |
| BGCNS_Transmitter, //!< A transmitter link. |
| BGCNS_Receiver //!< A receiver link. |
| } BGCNS_LinkType; |
| |
| /* ! @enum BGCNS_EnvmonParameter */ |
| /* ! @brief Enumerates the various environmental monitor parameters. */ |
| /* ! @see _BGCNS_ServiceDirectory::getEnvmonParm */ |
| /* ! @see _BGCNS_ServiceDirectory::setEnvmonParm */ |
| typedef enum { |
| BGCNS_envmon_period = 0, |
| BGCNS_envmon_policy, |
| BGCNS_envmon_globintwire, |
| |
| /* temporary */ |
| BGCNS_envmon_duration, |
| BGCNS_envmon_ddrratio, |
| BGCNS_envmon_numparms |
| } BGCNS_EnvmonParameter; |
| |
| |
| #define BGCNS_RC_COMPLETE 0 //!< Indicates that the operation completed normally. |
| #define BGCNS_RC_CONTINUE 1 //!< Indicates that the operation is still in progress. |
| #define BGCNS_RC_TIMEOUT -1 //!< Indicates that the operation timed out. |
| #define BGCNS_RC_ERROR -2 //!< Indicates that the operation failed. |
| |
| #define BGCNS_NUM_DMA_RECEPTION_GROUPS 4 |
| #define BGCNS_NUM_DMA_RECEPTION_FIFOS_PER_GROUP 8 |
| |
| /* ! @brief Describes the mapping of physical torus reception FIFOs to DMA reception FIFOs (rmFIFOs). */ |
| /* ! The first dimension indexes DMA reception groups, which are a combination of PID0 and PID1 bits */ |
| /* ! from the DMA packet. */ |
| /* ! */ |
| /* ! The second dimension indexes through the different dimensions: X+, X-, Y+, Y-, Z+, Z-, high priority */ |
| /* ! and local copy. */ |
| typedef unsigned char BGCNS_ReceptionMap[BGCNS_NUM_DMA_RECEPTION_GROUPS][BGCNS_NUM_DMA_RECEPTION_FIFOS_PER_GROUP]; |
| |
| /* ! @brief Indicates that an interrupt is to be broadcast on all cores. */ |
| /* ! @see _BGCNS_ServiceDirectory::enableInterrupt */ |
| #define BGCNS_ALL_CORE_BROADCAST 0xFFFFFFFFu |
| |
| |
| /* ! @enum BGCNS_DeviceMasks */ |
| /* ! @brief Provides a list of masks for various Blue Gene devices */ |
| |
| typedef enum { |
| BGCNS_SRAM = 0x80000000u, |
| BGCNS_BIC = 0x40000000u, |
| BGCNS_Torus = 0x20000000u, |
| BGCNS_DevBus = 0x10000000u, |
| BGCNS_XEMAC = 0x08000000u, |
| BGCNS_LockBox = 0x04000000u, |
| BGCNS_Collective = 0x02000000u, |
| BGCNS_SRAM_Err = 0x01000000u, |
| BGCNS_DMA = 0x00800000u, |
| BGCNS_UPC = 0x00400000u |
| } BGCNS_DeviceMasks; |
| |
| /* ! @typedef BGCNS_ServiceDirectory */ |
| /* ! @struct _BGCNS_ServiceDirectory */ |
| /* ! @brief The service directory is a collection of function pointers to services */ |
| /* ! provided by the Common Node Services. */ |
| typedef struct _BGCNS_ServiceDirectory { |
| |
| /*------------------------------------------*/ |
| /*--- Informational services for the node --*/ |
| /*------------------------------------------*/ |
| |
| |
| int (*isIONode)(void); //!< Returns 1 if this is an I/O node; 0 if not. |
| |
| |
| /*-----------------------------------------------------------------*/ |
| /*--- Informational services for obtaining Raw personality data ---*/ |
| /*-----------------------------------------------------------------*/ |
| |
| unsigned int (*getPersonalitySize)(void); //!< Returns the size (in bytes) of the Blue Gene personality. |
| void* (*getPersonalityData)(void); //!< Returns a pointer to the raw personality data. |
| |
| |
| /*-----------------------------------------------*/ |
| /*--- Services for Symmetric Multi-Processing ---*/ |
| /*-----------------------------------------------*/ |
| |
| |
| unsigned (*getNumberOfCores)(void); //!< Returns the number of CPUs on this node. |
| |
| /* ! @brief Called by the kernel to activate a CPU. */ |
| /* ! @param[in] cpu The index of the cpu (core) to be activated. */ |
| /* ! @param[in] entry The (kernel) entry point function. This function will be invoked when */ |
| /* ! the CPU is actually activated. */ |
| /* ! @param[in] arg A pointer to the lone argument to be passed to the entry point. */ |
| /* ! @return Zero (0) if the CPU was succsessfully activated. Non-zero if the CPU was not */ |
| /* ! activated (e.g. invalid cpu argument, or the cpu has already been */ |
| /* ! activated). */ |
| /* ! @remarks See Section x of the Common Node Services overview for details. */ |
| int (*takeCPU)(unsigned cpu, void *arg, void (*entry)(unsigned cpu, void *arg)); |
| |
| |
| /*--------------------------------------*/ |
| /*--- Services for Blue Gene devices ---*/ |
| /*--------------------------------------*/ |
| |
| /* ! @brief Checks active devices for a clean termination state and returns 0 */ |
| /* ! if everything is nominal. Returns non-zero if any anomaly is */ |
| /* ! detected and logs violations. */ |
| /* ! @param[in] job_rc specifies the return code of the job that is terminating. */ |
| int (*terminationCheck)(int job_rc); |
| |
| /*-------------------------------*/ |
| /*--- Services for interrupts ---*/ |
| /*-------------------------------*/ |
| |
| |
| /* ! @brief Enables the specified interrupt. For all interrupts except inter-processor */ |
| /* ! interrupts, the interrupt will bendled by the specified core. */ |
| /* ! @param[in] group Specifies the Blue Gene interrupt group */ |
| /* ! @param[in] irq Specifies the interrupt index within the group */ |
| /* ! @param[in] itype Specifies the type of interrupt that hardware will present */ |
| /* ! for this group/irq. */ |
| /* ! @param[in] core Specifies which core will handle the interrupt. If specified as */ |
| /* ! BGCNS_ALL_CORE_BROADCAST, then all cores will handle the interrupt. */ |
| /* ! @return Returns zero (0) if the interrupt is enabled and returns non-zero if it was not */ |
| /* ! (including the case of bad arguments). */ |
| int (*enableInterrupt)(unsigned group, unsigned irq, BGCNS_InterruptType itype, unsigned core); |
| |
| /* ! @brief Disables the specified interrupt. */ |
| /* ! @param[in] group Specifies the Blue Gene interrupt group */ |
| /* ! @param[in] irq Specifies the interrupt index within the group */ |
| /* ! @return Returns zero (0) if the interrupt is disabled and returns non-zero if it was not */ |
| /* ! (including the case of bad arguments). */ |
| int (*disableInterrupt)(unsigned group, unsigned irq); |
| |
| /* ! @brief Queries the Blue Gene interrupt hardware for interrupts of the given */ |
| /* ! type and returns the group/IRQ. This service is typically used in the */ |
| /* ! context of an interrupt handler. Since multiple interrupt conditions */ |
| /* ! may be present, the service is typically invoked from the handler */ |
| /* ! (along with corresponding acknowledgement) until the return code */ |
| /* ! indicates that no more interrupts are present. */ |
| /* ! @param[out] group Specifies the Blue Gene interrupt group. The value is valid */ |
| /* ! only when the return code is 0. */ |
| /* ! @param[out] irq Specifies the interrupt index within the group. The value is */ |
| /* ! valid only when the reutrn code is zero. */ |
| /* ! @param[in] itype Specifies the type of interrupt being queried. */ |
| /* ! @return Returns zero (0) if an interrupt condition of the specified type exists. Returns -1 */ |
| /* ! if no such condition exists. */ |
| int (*getInterrupt)(BGCNS_InterruptType itype, unsigned* group, unsigned* irq); |
| |
| /* ! @brief Acknowledges the specified interrupt, thus clearing the interrupt */ |
| /* ! condition in the interrupt controller hardware. */ |
| /* ! @param[in] group Specifies the Blue Gene interrupt group */ |
| /* ! @param[in] irq Specifies the interrupt index within the group */ |
| /* ! @return Returns zero (0) if the interrupt is acknowledged and returns non-zero if it was not */ |
| /* ! (including the case of bad arguments). */ |
| /* ! @remarks Note that for some interrupts, it is not sufficient to only acknowledge */ |
| /* ! the interrupt; the hardware condition that triggered the interrupt may */ |
| /* ! also need to be cleared. */ |
| int (*acknowledgeInterrupt)(unsigned group, unsigned irq); |
| |
| /* ! @brief Raises the specified interrupt. */ |
| /* ! @param[in] group Specifies the Blue Gene interrupt group */ |
| /* ! @param[in] irq Specifies the interrupt index within the group */ |
| int (*raiseInterrupt)(unsigned group, unsigned irq); |
| |
| |
| /*------------------------*/ |
| /*--- Mailbox services ---*/ |
| /*------------------------*/ |
| |
| unsigned (*getMailboxMaximumConsoleInputSize)(void); //!< Returns the actual maximum console message input data size. |
| unsigned (*getMailboxMaximumConsoleOutputSize)(void); //!< Returns the actual maximum console message output data size. |
| |
| /* ! @brief Writes a text message to the output mailbox. */ |
| /* ! @param[in] msg a pointer to the message to be written. */ |
| /* ! @param[in] msglen the length (in bytes) of the message to be written. */ |
| /* ! @remarks As with all common services, the message data area must be mapped via */ |
| /* ! the TLB when the service is called. The behavior is not defined if this */ |
| /* ! is not the case. */ |
| /* ! @return Zero (0) if the message was written successfully, non-zero if anything went */ |
| /* wrong (including a message that is too large). */ |
| int (*writeToMailboxConsole)(char *msg, unsigned msglen); |
| |
| /* ! @brief Writes a text message to the output mailbox but does not wait for a */ |
| /* ! response back from the control system. When this service is used, */ |
| /* ! the caller must poll for completion using the testForOutboxCompletion */ |
| /* ! service. */ |
| /* ! @param[in] msg a pointer to the message to be written. */ |
| /* ! @param[in] msglen the length (in bytes) of the message to be written. */ |
| /* ! @remarks As with all common services, the message data area must be mapped via */ |
| /* ! the TLB when the service is called. The behavior is not defined if this */ |
| /* ! is not the case. */ |
| /* ! @return Zero (0) if the message was written successfully, non-zero if anything went */ |
| /* wrong (including a message that is too large). */ |
| int (*writeToMailboxConsole_nonBlocking)(char* msg, unsigned msglen); |
| |
| /* ! @brief Tests the outbox to see if the last message was picked up by the control */ |
| /* ! system. */ |
| /* ! @return Zero (0) if the last message was piecked and returns non-zero if it has not. */ |
| /* ! @remarks Typically the caller will invoke this service after having called */ |
| /* ! writeToMailboxConsole_nonBlocking and will then invoke this service in a */ |
| /* ! loop until zero is returned. */ |
| int (*testForOutboxCompletion)(void); |
| |
| /* ! @brief Reads a message from the input mail box. */ |
| /* ! @param msg a pointer to a data area into which the message will be placed. */ |
| /* ! @param maxMsgSize gives the size of the data area, i.e. the largest message */ |
| /* ! that may be safely received into the buffer. */ |
| /* ! @return The actual length of the message (0 if no message was receieved). */ |
| /* ! @remarks As with all common services, the message data area must be mapped */ |
| /* ! via the TLB when this service is called. The results are not defined if */ |
| /* ! this is not the case. */ |
| unsigned (*readFromMailboxConsole)(char *buf, unsigned bufsize); |
| |
| int (*testInboxAttention)(void); //!< Returns 1 if something is available in the input mailbox. |
| |
| int (*_no_longer_in_use_1_)(void); //!< Obsolete ... do not use. |
| |
| int (*writeToMailbox)(void* message, unsigned length, unsigned cmd); |
| |
| /*------------------------------------*/ |
| /*--- RAS and diagnostic services ---*/ |
| /*------------------------------------*/ |
| |
| /* ! @brief TBD */ |
| void (*machineCheck)(void *regs); |
| |
| /* ! @brief Writes a RAS event to the log. */ |
| /* ! @param[in] facility The facility (aka component). */ |
| /* ! @param[in] unit The unit (aka subcomponent). */ |
| /* ! @param[in] err_code The error code. */ |
| /* ! @param[in] numDetails The number of additional details. */ |
| /* ! @param[in] details The list of additional details. */ |
| /* ! @return Zero if the message was written, non-zero if some error condition occurred. */ |
| /* ! @see bgp/arch/include/common/bgp_ras.h for details on facility, unit and err_code. */ |
| int (*writeRASEvent)( unsigned facility, unsigned unit, unsigned short err_code, unsigned numDetails, unsigned details[] ); |
| |
| /* ! @brief Writes a RAS string to the log. */ |
| /* ! @param[in] facility The facility (aka component). */ |
| /* ! @param[in] unit The unit (aka subcomponent). */ |
| /* ! @param[in] err_code The error code. */ |
| /* ! @param[in] str The message string being written (ASCII encoded, null-terminated). Note that the length of this string is */ |
| /* ! limited to _BGP_RAS_ASCII_MAX_LEN characters. The implementation may choose to truncate the string if it exceeds this */ |
| /* ! length. */ |
| /* ! @return Zero if the entire message was written; non-zero if some error condition occurred (including the case where the */ |
| /* ! string was truncated). */ |
| /* ! @see bgp/arch/include/common/bgp_ras.h for details on facility, unit and err_code. */ |
| int (*writeRASString)( unsigned facility, unsigned unit, unsigned short err_code, char* str ); |
| |
| |
| /*---------------------------------*/ |
| /*--- Global Interrupt services ---*/ |
| /*---------------------------------*/ |
| |
| /* ! @brief A global (compute node) barrier. This call will block until all other compute nodes */ |
| /* ! in the partition also arrive at the barrier. */ |
| int (*globalBarrier)(void); |
| |
| /* ! @brief A global (compute node) barrier. This call will block until all other compute nodes */ |
| /* ! in the partition also arrive at the barrier or until the timeout is reached. */ |
| /* ! @param timeoutInMillis specifies the timeout duration. Units are milliseconds. */ |
| /* ! @return BGCNS_RC_COMPLETE if the barrier completed. BGCNS_RC_TIMEOUT if the barrier timed */ |
| /* ! out. BGCNS_RC_ERROR if some other error occurred. */ |
| int (*globalBarrierWithTimeout)(unsigned timeoutInMillis); |
| |
| |
| |
| /*-------------------------*/ |
| /*--- Network services ---*/ |
| /*-------------------------*/ |
| |
| |
| void (*initializeNetworks)(void); //!< @todo Is this is going away??? Talk to Andy |
| |
| void (*_no_longer_in_use_381)(void); //!< @warning Do not use |
| |
| void (*_no_longer_in_use_384)(void);//!< @warning Do not use |
| |
| |
| /*--------------------------*/ |
| /*--- DMA unit services ---*/ |
| /*--------------------------*/ |
| |
| #define BGCNS_DMA_CAPTURE_X_PLUS 0 //!< watch the X+ receiver |
| #define BGCNS_DMA_CAPTURE_X_MINUS 1 //!< watch the X- receiver |
| #define BGCNS_DMA_CAPTURE_Y_PLUS 2 //!< watch the Y+ receiver |
| #define BGCNS_DMA_CAPTURE_Y_MINUS 3 //!< watch the Y- receiver |
| #define BGCNS_DMA_CAPTURE_Z_PLUS 4 //!< watch the Z+ receiver |
| #define BGCNS_DMA_CAPTURE_Z_MINUS 5 //!< watch the Z- receiver |
| #define BGCNS_DMA_CAPTURE_DISABLE 7 //!< disable link capturing |
| |
| /* ! @brief Sets the link capture facility of the DMA unit to watch the specified */ |
| /* ! receiver (or disable). */ |
| /* ! @param[in] link Specifies the link being monitored. Use the BGCNS_DMA_CAPTURE_* */ |
| /* ! mnemonics defined above. */ |
| /* ! @return Zero if the operation succeeded, non-zero if it did not (e.g. an invalid */ |
| /* ! link was specified). */ |
| int (*setDmaLinkCapture)(int link); |
| |
| /* ! @brief Clears the link capture unit so that another packet can be captured. */ |
| void (*clearDmaLinkCapture)(void); |
| |
| #define BGCNS_RC_DMA_NO_PACKET_CAPTURED 0 |
| #define BGCNS_RC_DMA_CAPTURE_UNIT_ERROR -1 |
| #define BGCNS_RC_DMA_DATA_CONFLICT -2 //!< if initial read indicates a bad packet is captured but subsequent read shows bad packet not captured |
| #define BGCNS_RC_DMA_DATA_CONFLICT2 -3 //!< if bad packet is captured, but all the bytes are the same |
| /* ! @brief Reads the DMA link capture packets. */ |
| int (*readDmaLinkCapturePackets)(unsigned char* good_packet, int* good_packet_size, unsigned char* bad_packet, int* bad_packet_size); |
| |
| |
| #define BGCNS_DMA_ALL_GROUPS 0xFFFFFFFF |
| |
| /* ! @brief Sets FIFO controls for the DMA unit. */ |
| /* ! */ |
| /* ! An operation on facility BGCNS_InjectionFifo enables or disables a subset of the 128 DMA injection FIFOs. */ |
| /* ! The FIFOs are organized into four groups of 32. The mask argument is a bit mask (bit i controls the i-th imFIFO */ |
| /* ! within that group, that is the (group*32)+i imFIFO. */ |
| /* ! */ |
| /* ! An operation on facility BGCNS_ReceptionFifo enables or disables a subset of the 32 DMA reception FIFOs. */ |
| /* ! The group argument is ignored and the mask argument is a bit mask (bit i controls the i-th reception FIFO). */ |
| /* ! */ |
| /* ! An operation on facility BGCNS_ReceptionHeaderFifo enables or disables the header FIFO for the specified */ |
| /* ! group. The mask argument is ignored. Note that the header FIFO is typically used for debugging. */ |
| /* ! */ |
| /* ! An operation on facility BGCNS_InjectionFifoInterrupt enables or disables threshold interrupts for the */ |
| /* ! specified injection FIFO. Threshold interrupts occur if available space is less than the configured */ |
| /* ! threshold when the FIFO is used for a remote get operation. The group and mask arguments are as */ |
| /* ! described in the BGCNS_InjectionFifo operation (above). */ |
| /* ! */ |
| /* ! An operation on facility BGCNS_ReceptionFifoInterrupt enables or disables interrupts for the specified */ |
| /* ! reception FIFO(s). If enabled, an interrupt will occur when the reception FIFO's available space drops */ |
| /* ! below the configured threshold. The group argument selects the interrupt type (type 0, 1, 2 or 3). */ |
| /* ! The mask argument is a bit mask selecting one or more of the 32 normal reception FIFOs. */ |
| /* ! */ |
| /* ! An operation on facility BGCNS_ReceptionHeaderFifoInterrupt enables or disables interrupts for the specified */ |
| /* ! reception header FIFO. Reception header FIFOs are used for debug purposes only. */ |
| /* ! */ |
| /* ! An operation on facility BGCNS_InjectionCounterInterrupt enables or disables "Counter Hit Zero" interrupts. */ |
| /* ! The group argument does not specify counter group, but rather specifies interrupt 0, 1, 2 or 3. The mask */ |
| /* ! argument is a bit mask that selects one or more counter subgroups to operate on (the 256 injection counters */ |
| /* ! are partitioned into 32 subgroups of 8 counters). */ |
| /* ! */ |
| /* ! An operation on facility BGCNS_ReceptionCounterInterrupt enables or disables "Counter Hit Zero" interrupts */ |
| /* ! for reception counters. The group and mask arguments are the as as described in the the */ |
| /* ! BGCNS_InjectionCounterInterrupt operation (above). */ |
| /* ! */ |
| /* ! The buffer argument is used as a means to save/restore in an opaque manner. This is achieved by passing */ |
| /* ! a non-NULL buffer to a disable operation and subsequently passing that buffer during a reenable */ |
| /* ! operation (the buffer is used to snapshot state). */ |
| /* ! */ |
| /* ! */ |
| /* ! @code */ |
| /* ! +---------------------------------+-----------+---------+-------+ */ |
| /* ! | Facility | group | mask | Notes | */ |
| /* ! +---------------------------------+-----------+---------+-------+ */ |
| /* ! | BGCNS_InjectionFifo | 0..3 | 32 bits | [1] | */ |
| /* ! +---------------------------------+-----------+---------+-------+ */ |
| /* ! | BGCNS_ReceptionFifo | n/a | 32 bits | [2] | */ |
| /* ! +---------------------------------+-----------+---------+-------+ */ |
| /* ! | BGCNS_ReceptionHeaderFifo | 0..3, ALL | N/A | | */ |
| /* ! +---------------------------------+-----------+---------+-------+ */ |
| /* ! | BGCNS_InjectionFifoInterrupt | 0..3 | 32 bits | [1] | */ |
| /* ! +---------------------------------+-----------+---------+-------+ */ |
| /* ! | BGCNS_ReceptionFifoInterrupt | 0..3 | 32 bits | [3] | */ |
| /* ! +---------------------------------+-----------+---------+-------+ */ |
| /* ! | BGCNS_InjectionCounterInterrupt | 0..3 | 32 bits | [3][4]| */ |
| /* ! +---------------------------------+-----------+---------+-------+ */ |
| /* ! | BGCNS_ReceptionCounterInterrupt | 0..3 | 32 bits | [3][4]| */ |
| /* ! +---------------------------------+-----------+---------+-------+ */ |
| /* ! */ |
| /* ! [1] There are 128 injection FIFOs partitioned into 4 groups of 32. */ |
| /* ! [2] There are 32 normal reception FIFOs in BG/P. */ |
| /* ! [3] There are 4 interrupt lines. The group argument selects one these 4. */ |
| /* ! [4] There are 256 counters of each type (injection and reception). The */ |
| /* ! 32-bit mask partitions them into groups of 8. */ |
| /* ! */ |
| /* ! @endcode */ |
| /* ! */ |
| /* ! @param[in] operation defines the type of operation being performed (enable, disable, or re-enable). */ |
| /* ! @param[in] facility defines the type of FIFO being configured. */ |
| /* ! @param[in] group is interpreted differently based on the facility. */ |
| /* ! @param[in] mask is interpreted differently based on the facility. */ |
| /* ! @param[out] buffer is interpreted differently based on the operation and facility. It is generally used to capture */ |
| /* ! a copy of the facility's current state in an enable operation (and may be null, in which case it is ignored). It is */ |
| /* ! generally used as the value to be loaded in a re-enable operation. In this manner, a state value captured by an enable */ |
| /* ! operation may be easily restored by a subsequent re-enable operation. The buffer argument is generally ignored by */ |
| /* ! disable operations. */ |
| int (*setDmaFifoControls)(BGCNS_FifoOperation operation, BGCNS_FifoFacility facility, unsigned group, unsigned mask, unsigned* buffer); |
| |
| /* ! @brief Maps injection FIFOs onto physical (torus hardware) FIFOs. */ |
| /* ! @param[in] group specifies the injection FIFO group. */ |
| /* ! @param[in] fifoIds is an array of length numberOfFifos whose elements are the identifiers of the imFIFO (within that */ |
| /* ! given group). */ |
| /* ! @param[in] injection_map is an array of length numberOfFifos whose elements are 8-bit masks identifying which of the */ |
| /* ! physical torus injection FIFOs are mapped. Bits 0-3 correspond to torus group 0, and bits 4-7 correspond to torus */ |
| /* ! group 1. Bits 3 and 7 are the high priority FIFOs. */ |
| /* ! @param[in] numberOfFifos describes the number of elements contained in the fifoIds and injection_map arguments. */ |
| /* ! @return Zero if the map was properly set. Non-zero if it was not, including the case of illegal arguments. */ |
| /* ! @note In BG/P, there are 128 injection FIFOs partitioned into 4 groups of 32. So the legal range of the group */ |
| /* ! argument is 0..3 and the legal range for the fifoIds[] elements is 0..31. */ |
| |
| int (*setDmaInjectionMap)(unsigned group, unsigned fifoIds[], unsigned char injection_map[], unsigned numberOfFifos); |
| |
| /* ! @brief Enables or disables "local copy" behavior for the specified injection FIFOs. A local copy injection FIFO */ |
| /* ! can be used to perform memory copies within a node via the DMA engine. */ |
| /* ! @param[in] operation specifies whether local copies is being enabled or disabled on the specified FIFOs. The BGCNS_Reenable */ |
| /* ! operation is not supported. */ |
| /* ! @param[in] group specifies the injection FIFO group. */ |
| /* ! @param[in] bits selects one or more injection FIFOs from within the group on which to operate. */ |
| /* ! @return Zero if the operation succeeded; non-zero if it did not. */ |
| /* ! @note In BG/P, there are 128 injection FIFOs partitioned into 4 groups of 32. So the legal range of the group */ |
| /* ! argument is 0..3. */ |
| int (*setDmaLocalCopies)(BGCNS_FifoOperation operation, unsigned group, unsigned bits); |
| |
| /* ! @brief Enables or disables the priority bit for the specified injection FIFOs. The priority bit */ |
| /* ! is used by the hardware arbitration (details are not further documented here). */ |
| /* ! @param[in] operation specifies whether priority bits are being set or cleared. */ |
| /* ! @param[in] group specifies the injection FIFO group. */ |
| /* ! @param[in] bits selects one or more injection FIFOs from within the group on which to operate. */ |
| /* ! @note In BG/P, there are 128 injection FIFOs partitioned into 4 groups of 32. So the legal range of the group */ |
| /* ! argument is 0..3. */ |
| int (*setDmaPriority)(BGCNS_FifoOperation operation, unsigned group, unsigned bits); |
| |
| /* ! @brief Sets the mapping from physical (torus hardware) reception FIFOs to reception FIFOs. The hardware supports */ |
| /* ! 8 torus FIFOs (six torus dimensions plus high priority plus local copy). Furthermore, the hardware supports */ |
| /* ! 4 groups as derived from the PID0 and PID1 bits of the DMA packet. Thus the mapping is a 4 x 8 matrix of */ |
| /* ! reception FIFO ids. */ |
| /* ! @param[in] torus_reception_map maps {group} X {torus-hardware-FIFOs} --> reception FIFOs. */ |
| /* ! @param[in] fifo_types is an array of N values specifying the type of each normal reception FIFO (see also threshold). For BGP, */ |
| /* ! N=2 (there are 32 normal reception FIFOs). */ |
| /* ! @param[in] header_types is an array of N values specifying the type of each reception header FIFO (see also threshold). For */ |
| /* ! BGP, N=4 (there are 4 reception header FIFOs). Note that reception header FIFOs are typically only used for debugging purposes. */ |
| /* ! @param[in] threshold is an array of N threshold values. The value threshold[i] specifies the threshold value for reception */ |
| /* ! FIFO type i. If reception FIFO interrupts are enabled (see setDmaFifoControls) and a reception FIFO's available space drops */ |
| /* ! below its threshold, an interrupt is driven. For BGP, N=2 (there are type 0 and type 1 injection FIFOs). */ |
| int (*setDmaReceptionMap)( BGCNS_ReceptionMap torus_reception_map, unsigned fifo_types[], unsigned header_types[], unsigned threshold[]); |
| |
| /* ! @brief Gets the reception map. */ |
| /* ! @see setDmaReceptionMap for descriptions of the map and arguments. */ |
| int (*getDmaReceptionMap)( BGCNS_ReceptionMap torus_reception_map, unsigned fifo_types[], unsigned short* store_headers, unsigned header_types[], unsigned threshold[]); |
| |
| |
| /* ! @deprecated */ |
| int (*_used_to_be_clearDmaFullReceptionFifo__removed)(void); |
| |
| |
| /* ! @brief Resets the MAC unit's PHY. */ |
| /* ! @return Zero if the unit was properly reset. Returns non-zero if some error occurred. */ |
| /* ! @deprecated See macResetPHY_nonBlocking. */ |
| int (*macResetPHY)(void); |
| |
| /* ! @brief Tests the MAC unit's link. */ |
| /* ! @param[in] link_type specifies the type of link to be tested. */ |
| /* ! @return One (1) if the link is active; zero (0) if it is not. */ |
| /* ! @deprecated See macTestLink_nonBlocking */ |
| int (*macTestLink)(BGCNS_LinkType link_type); |
| |
| /* ! @brief Reads one of the MAC's XGMII registers. */ |
| /* ! @param[in] device_address */ |
| /* ! @param[in] port_address */ |
| /* ! @param[in] register_address */ |
| /* ! @return The register's value or a negative number if some error occurred. */ |
| /* ! @deprecated Low level MAC register access is being eliminated. */ |
| int (*macXgmiiRead)(unsigned device_address, unsigned port_address, unsigned register_address); |
| |
| /* ! @brief Writes one of the MAC's XGMII registers. */ |
| /* ! @param[in] device_address */ |
| /* ! @param[in] port_address */ |
| /* ! @param[in] register_address */ |
| /* ! @param[in] value */ |
| /* ! @return Zero (0) if the register was successfully written; non-zero if some error occurred. */ |
| /* ! @deprecated Low level MAC register access is being eliminated. */ |
| int (*macXgmiiWrite)(unsigned device_address, unsigned port_address, unsigned register_address, unsigned value); |
| |
| |
| /* ! @brief Trains SerDes in a non-blocking manner. The standard usage is to inititate */ |
| /* ! training with trainSerDes(1), check the return code, and then continue to invoke */ |
| /* ! trainSerDes(0) as long as the return code is BGCNS_RC_CONTINUE. */ |
| /* ! @param[in] reset Should be 1 when initiating a retraining sequence and 0 for any */ |
| /* ! continuations. */ |
| /* ! @return BGCNS_RC_CONTINUE if training is still ongoing (the caller should re-invoke */ |
| /* ! the service again (with reset=0). BGCNS_RC_COMPLETE if training is complete. */ |
| /* ! BGCNS_ERROR if some error has occurred. */ |
| int (*trainSerDes)(int reset); |
| |
| /* ! @brief Fetches the value of the specified control parameter of the environmental monitor. */ |
| /* ! @param[in] parameter Parameter to retrieve. Should be a valid parameter in the BGCNS_EnvmonParameter enumeration */ |
| /* ! @param[in] value Pointer to the storage location that will contain the parameter's value when the function successfully returns. */ |
| /* ! @return Zero if the register was successfully fetched; non-zero if some error occurred. */ |
| int (*getEnvmonParm)(BGCNS_EnvmonParameter parameter, unsigned int* value); |
| |
| /* ! @brief Stores a value to the specified control parameter of the environmental monitor */ |
| /* ! @param[in] parameter Parameter to store. Should be a valid parameter in the BGCNS_EnvmonParameter enumeration */ |
| /* ! @param[in] value New value for the parameter */ |
| /* ! @return Zero if the register was successfully fetched; non-zero if some error occurred. */ |
| int (*setEnvmonParm)(BGCNS_EnvmonParameter parameter, unsigned int value); |
| |
| /* ! @brief Performs checks and ensures that the node will continue to operate within tolerances. */ |
| /* ! @note MUST be called regularly as indicated by nextCallbackTime parameter */ |
| /* ! @param[in] nextCallbackTime Upon returning, this will contain the PPC Timebase register value indicating when the next */ |
| /* ! time the operating system needs to call performEnvMgmt. Failure to do so may result in poorly performing */ |
| /* ! nodes or shutdown of the block / rack. */ |
| int (*performEnvMgmt)(unsigned long long* nextCallbackTime); |
| |
| |
| /* ! @brief Writes a RAS message to the output mailbox but does not wait for a */ |
| /* ! response back from the control system. When this service is used, */ |
| /* ! the caller must poll for completion using the testForOutboxCompletion */ |
| /* ! service. */ |
| /* ! @param[in] facility The facility (aka component). See bgp_ras.h for a list of facilities. */ |
| /* ! @param[in] unit The unit (aka subcomponent). See bgp_ras.h for a list of units. */ |
| /* ! @param[in] err_code The error code. See bgp_ras.h for a list of error code.s */ |
| /* ! @param[in] numDetails The number of additional details. */ |
| /* ! @param[in] details The list of additional details. */ |
| /* ! @return Zero if the message was written, non-zero if some error condition occurred. */ |
| int (*writeRASEvent_nonBlocking)( unsigned facility, unsigned unit, unsigned short err_code, unsigned numDetails, unsigned details[] ); |
| |
| /* ! @brief Writes a RAS message to the output mailbox but does not wait for a */ |
| /* ! response back from the control system. When this service is used, */ |
| /* ! the caller must poll for completion using the testForOutboxCompletion */ |
| /* ! service. */ |
| /* ! @param[in] facility The facility (aka component). See bgp_ras.h for a list of facilities. */ |
| /* ! @param[in] unit The unit (aka subcomponent). See bgp_ras.h for a list of units. */ |
| /* ! @param[in] err_code The error code. See bgp_ras.h for a list of error code.s */ |
| /* ! @param[in] str The message string being written (ASCII encoded, null-terminated). Note that the length of this string is */ |
| /* ! limited to _BGP_RAS_ASCII_MAX_LEN characters. The implementation may choose to truncate the string if it exceeds this */ |
| /* ! length. */ |
| /* ! @return Zero if the entire message was written; non-zero if some error condition occurred (including the case where the */ |
| /* ! string was truncated). */ |
| /* ! @return Zero if the message was written, non-zero if some error condition occurred. */ |
| int (*writeRASString_nonBlocking)( unsigned facility, unsigned unit, unsigned short err_code, char* str ); |
| |
| /* ! @brief Sets the core's timebase registers to the specified value. */ |
| /* ! @param[in] newtime The new 64-bit timebase */ |
| /* ! @return Zero if the timebase was successfully set, non-zero if some error condition occurred. */ |
| /* ! @deprecated */ |
| int (*synchronizeTimebase)(unsigned long long newtime); |
| |
| /* ! @brief Sets the node's DMA physical protection settings. */ |
| /* ! @note on BGP, there are a maximum of 8 read ranges and 8 write ranges */ |
| /* ! @return Zero if the DMA ranges were set, non-zero if some error condition occurred. */ |
| int (*dmaSetRange)(unsigned numreadranges, unsigned long long* read_lower_paddr, unsigned long long* read_upper_paddr, |
| unsigned numwriteranges, unsigned long long* write_lower_paddr, unsigned long long* write_upper_paddr); |
| |
| /* ! @brief Checks the status of the devices and reports correctible RAS (if any) */ |
| /* ! @param[in] clear_error_counts If non-zero, function will also reset the hardware error counters after posting any RAS. */ |
| /* ! @return Zero if successful, non-zero if some error condition occurred. */ |
| int (*statusCheck)(unsigned clear_error_counts); |
| |
| /* ! @brief Stops the DMA and clears any reception unit failure */ |
| int (*stopDma)(void); |
| |
| /* ! @brief Starts the DMA */ |
| int (*startDma)(void); |
| |
| /* ! @brief Performs a hard exit. The status code is provided to the control system. */ |
| /* ! @return This service never returns. */ |
| void (*exit)(int rc); |
| |
| /* ! @brief Resets the MAC unit's PHY but does not block. */ |
| /* ! @param[in] reset indicates whether this is the beginning (1) or a continuation (0) of a */ |
| /* ! reset sequence. That is, callers should initiate a reset sequence with reset=1 and then */ |
| /* ! if receiving a return code of BGCNS_RC_CONTINUE, should invoke this servicate again with */ |
| /* ! reset=0. */ |
| /* ! @param[in] timeoutInMillis the (approximate) number of milliseconds that this service can have */ |
| /* ! before returning. If the allotted time is not sufficient, the service will return BGCNS_RC_CONTINUE */ |
| /* ! to indicate that it needs additional time. */ |
| /* ! @return BGCNS_RC_COMPLETE if the unit was properly reset. BGCNS_RC_CONTINUE if the reset operation is */ |
| /* ! not yet complete. BGCNS_RC_ERROR if the reset operation failed. */ |
| int (*macResetPHY_nonBlocking)(int reset, unsigned timeoutInMillis); |
| |
| /* ! @brief Tests the MAC unit's link but does not block. */ |
| /* ! @param[in] link_type specifies the type of link to be tested. */ |
| /* ! @param[out] result points to the link status, which is valid only when the return code is */ |
| /* ! BGCNS_RC_COMPLETE. A value of one (1) indicates that the link is active; zero (0) */ |
| /* ! indicates that it is inactive. */ |
| /* ! @param[in] reset indicates whether this is the beginning (1) or a continuation (0) of a */ |
| /* ! test link sequence. That is, callers should initiate a sequence with reset=1 and then */ |
| /* ! if receiving a return code of BGCNS_RC_CONTINUE, should invoke this service again with */ |
| /* ! reset=0. */ |
| /* ! @param[in] timeoutInMillis the (approximate) number of milliseconds that this service can have */ |
| /* ! before returning. If the allotted time is not sufficient, the service will return BGCNS_RC_CONTINUE */ |
| /* ! to indicate that it needs additional time. */ |
| /* ! @return BGCNS_RC_COMPLETE if the test is complete (result is valid only in this case). BGCNS_RC_CONTINUE */ |
| /* ! if the reset operation is not yet complete. BGCNS_RC_ERROR if the reset operation failed. */ |
| int (*macTestLink_nonBlocking)(BGCNS_LinkType link_type, unsigned* result, int reset, unsigned timeoutInMillis); |
| |
| void * _not_in_use_1068; |
| void * _not_in_use_1069; |
| |
| |
| /* ! @brief Indicates that a new job is about to start. */ |
| /* ! @return Zero (0) if CNS is ready for a new job to start. Returns non-zero otherwise. */ |
| int (*startNextJob)(void); |
| |
| /* ! @brief Indicates that the CNS should use the specified virtual address when accessing the */ |
| /* ! given device. When a device is remapped, CNS will no longer make any attempt to map */ |
| /* ! a TLB to access that device -- it is the responsibility of the kernel to handle the */ |
| /* ! TLB either proactively or reactively (via a fault). */ |
| /* ! @param[in] device specifies the device being mapped. */ |
| /* ! @param[in] base_address is the root virtual address of the device. The address should be */ |
| /* ! naturally aligned (relative to the size of the device). See the seciton Reserved and */ |
| /* ! Preferred Addresses for more information. */ |
| /* ! @return Zero (0) if the device was successfully remapped. Returns non-zero if it was not. */ |
| /* ! @remarks The lock box is in active use by CNS during early boot and thus it is not */ |
| /* ! possible to remap the BGCNS_LockBox device until all cores are activated by the kernel */ |
| /* ! (that is, takeCPU has been called for all cores). */ |
| int (*mapDevice)(BGCNS_DeviceMasks device, void* base_address); |
| |
| /* ! @brief Enables barriers on the specified channel. */ |
| /* ! @param channel specifies the channel being enabled. */ |
| /* ! @param user_mode indicates whether the barrier is to be used in user-mode code. */ |
| /* ! @return Zero if global barriers were enabled. Returns non-zero if the request could not be */ |
| /* ! completed, including the case of attempting to enable a reserved channel. */ |
| int (*enableBarrier)(unsigned int channel, int user_mode); |
| |
| /* ! @brief Disables barriers on the specified channel. */ |
| /* ! @return Zero if global barriers were disabled. Returnsnon-zero if the request could not be */ |
| /* ! completed, including the case of attempting to disable a reserved channel. */ |
| int (*disableBarrier)(unsigned int channel); |
| |
| /* ! @brief A global barrier that does not block indefinitely. */ |
| /* ! @param channel indicates the GLINT hardware channel to use. */ |
| /* ! @param reset indicates whether this is the beginning (1) or a continuation (0) of a barrier */ |
| /* ! sequence. That is, caller should inititate a barrier operation by passing reset=1 and then, */ |
| /* ! if receiving a return code of BGCNS_RC_CONTINUE, should invoke the service again with */ |
| /* ! reset=0. */ |
| /* ! @param timeoutInMillis is the (approximate) number of milliseconds that this service is allowed */ |
| /* ! to wait for barrier participants before returning to the caller. */ |
| /* ! @return BGCNS_RC_COMPLETE indicates that all participants have arrived at the barrier. BGCNS_RC_CONTINUE */ |
| /* ! indicates that not all partipants arrived within the alloted timeout period. BGCNS_RC_ERROR */ |
| /* ! indicates that other problem has been detected. */ |
| /* ! @remarks This service is not thread safe. It is considered a programming error to invoke it */ |
| /* ! from multiple threads concurrently and the behavior is not defined. */ |
| int (*globalBarrier_nonBlocking)(unsigned channel, int reset, unsigned timeoutInMillis); |
| |
| /* ! @brief Restart kernel in cycle reproducibility mode. */ |
| /* ! @return Zero if no restart was required for reproducibility. */ |
| /* ! @remarks This service must be called from each core and only after all I/O operations have been completed. */ |
| /* ! Processors will be reset and kernels will start again. */ |
| int (*setupReproducibility)(void); |
| |
| } BGCNS_ServiceDirectory; |
| |
| /* ! @deprecated */ |
| /* ! @typedef BGCNS_DeprecatedServicesDirectory */ |
| /* ! @struct _BGCNS_DeprecatedServices */ |
| /* ! @brief These services exist for historical reasons and are not further documented here. */ |
| /* ! They may not be available in future releases of CNS. */ |
| typedef struct _BGCNS_DeprecatedServices { |
| int (*torusTermCheck)(int* nonFatalRc); |
| int (*torusLinkErrCheck)(int* nonFatalRc); |
| int (*torusCRCExchange)(void); |
| int (*collectiveConfigureClassInternal)(unsigned virtualTree, unsigned short specifier); |
| int (*collectiveConfigureClass)(unsigned virtualTree, unsigned short specifier); |
| unsigned (*collectiveGetClass)(unsigned virtualTree); |
| int (*collectiveInit)(void); |
| int (*collectiveRelease)(void); |
| int (*collectiveHardReset)(void); |
| int (*netbusTermCheck)(void); |
| unsigned (*getSerDesLinkStatus)(void); |
| int (*dmaTermCheck)(void); |
| } BGCNS_DeprecatedServicesDirectory; |
| |
| /* ! @typedef BGCNS_Descriptor */ |
| /* ! @struct _BGCNS_Descriptor */ |
| /* ! @brief The Common Node Services descriptor. This descriptor provides information to the kernel regarding */ |
| /* ! the CNS memory region as well as a service directory. The descriptor is passed to the kernel */ |
| /* ! upon boot and must not be altered by the kernel. */ |
| typedef struct _BGCNS_Descriptor { |
| BGCNS_ServiceDirectory* services; //!< A pointer to the services directory. |
| unsigned baseVirtualAddress; //!< The virtual address of the beginning of the CNS memory region. |
| unsigned size; //!< The size (in bytes) of the CNS memory region. |
| unsigned basePhysicalAddress; //!< The physical address of the CNS memory region. |
| unsigned basePhysicalAddressERPN; //!< The extended real page number of the CNS memory region. |
| unsigned bgcns_private_in_use; //!< Undefined. This field is for internal use only and may disappear at any time. |
| BGCNS_DeprecatedServicesDirectory* deprecatedServices; //!< @deprecated undocumented |
| unsigned version; //!< The CNS version |
| } BGCNS_Descriptor; |
| |
| |
| |
| #endif /* !__ASSEMBLY */ |
| #endif /* _BGCNS_H */ |
