Error Handling APIs

With few exceptions, all OpenNSL API routines return an integer indicating the success or error status of the call. All error codes (except OPENNSL_E_NONE) are negative and are one of the values given in table error_codes . Success is usually indicated by the return value of OPENNSL_E_NONE, which is defined to be zero. Some routines may also return other success indications as positive numbers. Any such deviations from the table 'error_codes' will be described in the individual API routine descriptions.

In the API descriptions, an arbitrary error return code is specified by writing OPENNSL_E_XXX. This means that the routine will return some error code listed in table 'error_codes'.

Routines may also propagate error indications from lower-level driver and utility routines. The error codes thus propagated are compatible with these OpenNSL error codes, and can be treated identically.

Access to the error definitions is through the include file <opennsl/error.h>.

Checking for the failure of an API call can be done by testing if its return value is negative or by using OPENNSL_FAILURE macro:

int rv;
rv = opennsl_port_speed_set(unit, port, 1000);
if (rv < 0) {
    /* failure */
}

if (OPENNSL_FAILURE(rv)) {
    /* failure */ 
}

TABLE: Error Codes :: ERROR CODE [String Value] DESCRIPTION

• OPENNSL_E_NONE [Ok] The routine completed successfully.

• OPENNSL_E_INTERNAL [Internal error] Some internal operations failed in an unexpected way. This usually indicates that an access to some hardware resource failed.

• OPENNSL_E_MEMORY [Out of memory] Dynamically allocated memory was not available to complete the operation.

• OPENNSL_E_UNIT [Invalid unit] The first argument of any OpenNSL API routine is a unit number. This error occurs if that number does not refer to a currently attached unit.

• OPENNSL_E_PARAM [Invalid parameter] A parameter to a OpenNSL API routines was invalid. A null pointer value may have been passed to the routine, or an integer parameter may be outside of its allowed range.

• OPENNSL_E_EMPTY [Table empty] The routine expected a table not to be empty.

• OPENNSL_E_FULL [Table full] The routine could not add an entry to the table

• OPENNSL_E_NOT_FOUND [Entry not found] The specific entry in a table could not be found.

• OPENNSL_E_EXISTS [Entry exists] The specific entry was already in a table

• OPENNSL_E_TIMEOUT [Operation timed out] The routine started an operation that did not complete.

• OPENNSL_E_BUSY [Operation still running] The routine tried to start an operation, but a previous operation was still running.

• OPENNSL_E_FAIL [Operation failed] The routine attempted an operation that could not be completed. This may be because of a hardware failure or a configuration failure.

• OPENNSL_E_DISABLED [Operation disabled] The routine could not complete because a required feature was temporarily disabled. This often relates to auto-negotiation.

• OPENNSL_E_BADID [Invalid identifier] An identifier was not valid.

• OPENNSL_E_RESOURCE [No resources for operation] The routine needed more hardware resources than were available.

• OPENNSL_E_CONFIG [Invalid configuration] The hardware does not support the requested configuration.

• OPENNSL_E_UNAVAIL [Feature unavailable] The hardware does not support the requested routine.

• OPENNSL_E_INIT [Feature not initialized] The routine used a part of the API that was not yet initialized.

• OPENNSL_E_PORT [Invalid port] A port parameter was given that is not valid.