diff options
Diffstat (limited to 'src/ppe/hwpf/fapi/docs/topics')
| -rwxr-xr-x | src/ppe/hwpf/fapi/docs/topics/DEPRECATED.md | 81 | ||||
| -rwxr-xr-x | src/ppe/hwpf/fapi/docs/topics/Examples.md | 246 | ||||
| -rwxr-xr-x | src/ppe/hwpf/fapi/docs/topics/Ffdc.md | 149 | ||||
| -rwxr-xr-x | src/ppe/hwpf/fapi/docs/topics/README.md | 166 |
4 files changed, 0 insertions, 642 deletions
diff --git a/src/ppe/hwpf/fapi/docs/topics/DEPRECATED.md b/src/ppe/hwpf/fapi/docs/topics/DEPRECATED.md deleted file mode 100755 index 39df626..0000000 --- a/src/ppe/hwpf/fapi/docs/topics/DEPRECATED.md +++ /dev/null @@ -1,81 +0,0 @@ -@deprecated Functions which were either not found used in the -hostboot code or have other ways to perform the same operation -with the new buffers are candidates for deprecation. They are listed -here so if you're looking for something you might find that it's -deprecated and not been implemented. If there's something in this -list which should be implemented, let someone know and we can -implement it.<br> -- setDoubleWordLength(uint32_t i_newNumDoubleWords);<br> -- setWordLength(uint32_t i_newNumWords);<br> -- setHalfWordLength(uint32_t i_newNumHalfWords);<br> -- setByteLength(uint32_t i_newNumBytes);<br> -- setBitLength(uint32_t i_newNumBits);<br> -- setCapacity (uint32_t i_newNumWords);<br> -- shrinkBitLength(uint32_t i_newNumBits);<br> -- growBitLength(uint32_t i_newNumBits);<br> -Replaced with std::container operations -- shiftRight(uint32_t i_shiftnum, uint32_t i_offset = 0);<br> -Replaced with operator>> as offset appears unused<br> -- shiftLeft(uint32_t i_shiftnum, uint32_t i_offset = 0xFFFFFFFF);<br> -Replaced with operator<< as offset appears unused<br> -- shiftRightAndResize(uint32_t i_shiftnum, uint32_t i_offset = 0);<br> -- shiftLeftAndResize(uint32_t i_shiftnum);<br> -- rotateRight(uint32_t i_rotatenum);<br> -- rotateLeft(uint32_t i_rotatenum);<br> -- flushTo0(); and flushTo1();<br> -Replaced with flush<X>() where X can be {0,1}<br> -- applyInversionMask(const uint32_t * i_invMask, uint32_t - i_invByteLen);<br> -- applyInversionMask(const ecmdDataBufferBase & i_invMaskBuffer, - uint32_t i_invByteLen);<br> -- insert(const ecmdDataBufferBase & i_bufferIn, uint32_t i_targetStart, - uint32_t i_len, uint32_t i_sourceStart = 0);<br> - insert(const uint32_t * i_data, uint32_t i_targetStart, uint32_t - i_len, uint32_t i_sourceStart = 0);<br> -It appears from the usage that the insert functions were used like a -initializer list - given a chunk of data, insert at bit 0. -Other useages have been replaced with a templated version for -variable_buffers and bit operations for integral buffers.<br> -- insertFromRight<br> -Replaced with a templated version for -variable_buffers and bit operations for integral buffers.<br> -- extract API<br> -Replaced with a templated version for -variable_buffers and bit operations for integral buffers.<br> -- setOr API/merge API<br> -- concat( ... );<br> -Replaced with operator+() and operator+=()<br> -- setOr(const uint32_t * i_data, uint32_t i_startbit, - uint32_t i_len);<br> - merge() -Replaced with operator|=() as it looks like startbit is always 0 -and len is always the length of i_data. Merge is the same I think<br> -- setXor(const ecmdDataBufferBase & i_bufferIn, uint32_t i_startbit, - uint32_t i_len); -Replaced with operator|=() as it looks like startbit is always 0 -and len is always the length of i_data.<br> -- setAnd(const ecmdDataBufferBase & i_bufferIn, uint32_t i_startbit, - uint32_t i_len);<br> -Replaced with operator&=() as it looks like startbit is mostly 0 -and len is mostly the length of i_data. The few cases seen where -this isn't the case, a uint64_t mask would work better.<br> -- copy(ecmdDataBufferBase & o_copyBuffer) const -Replaced with operator=() -- memCopyIn, memCopyOut -- flattenSize(void) const; -- flatten(uint8_t * o_data, uint32_t i_len) const; -- unflatten(const uint8_t * i_data, uint32_t i_len); -- oddParity() -- evenParity() -- shareBuffer(ecmdDataBufferBase* i_sharingBuffer); -- compressBuffer(ecmdCompressionMode_t i_mode = ECMD_COMP_PRD); -- uncompressBuffer(); -- isBufferCompressed(); -- setWord(), setHalfWord(), etc. -Replaced with a templated version, set<type>(); -- getDoubleWordLength(), getDoubleLength -Replaced with a templated version taking the type as an argument -- getCapacity() -- writeBit(bits_type i_bit, uint32_t i_value); -Replaced with set operations (this might be needed?) -e
\ No newline at end of file diff --git a/src/ppe/hwpf/fapi/docs/topics/Examples.md b/src/ppe/hwpf/fapi/docs/topics/Examples.md deleted file mode 100755 index e7ccb02..0000000 --- a/src/ppe/hwpf/fapi/docs/topics/Examples.md +++ /dev/null @@ -1,246 +0,0 @@ - -# Examples And Frequently Asked Questions - -## Buffers - -### Create a buffer of 32 bits and initialize it. - - fapi2::buffer<uint32_t> data(0xAA55FFAA); - -### Flip bit 0 - - data.flipBit<0>(); - -### Invert the buffer - - data.invert(); - -### Reset it's value - - data = 0xFFFFFFFF; - -### Create a mask using an anonymous object - - my_buffer &= buffer<T>().setBit<B>.invert(); - -### Create an 8 bit buffer, initialize it, and flip some bits around - - fapi2::buffer<uint8_t>(0xA5).flipBit<5>().flipBit<5>() == 0xA5; - -## Operations and Things -### Is the FAPI_TRY / 'clean_up:' method, the recommended method for doing put/getscoms? - -Yes, FAPI_TRY is the preferred wrapper for put/get scom as well as other operations which used to do the do/while/break dance based on the fapi return code. -A thread-local fapi return code, fapi2::current_err has been introduced to help with the housekeeping. - -Feel free to decompose the FAPI_TRY pattern if you have clean_up requirements which make FAPI_TRY too simplistic. - - -## Targets - -### Create a processor target - - fapi2::Target<fapi2::TARGET_TYPE_PROC_CHIP> A(PROCESSOR_CHIP_A); - -### Define a function which takes only a processor as an argument, enforced by the compiler - - void takesProc( const fapi2::Target<fapi2::TARGET_TYPE_PROC_CHIP>& V ); - -### How do I pass TARGET_TYPE_X into putScom? - -It should "just work." fapi2::putScom is defined as a template. -Basically any TargetType will match. So, - - Target<TARGET_TYPE_XBUS> foo; - Target<TARGET_TYPE_ABUS> bar; - -will both match fapi::putScom in it's more generic sense. However, platforms -might specialize the hw_access templates. For example, if the operation to -perform a putScom on an XBUS is different than accessing other targets, the -platform needs to specialize for XBUS. - - template<> - fapi2::ReturnCode fapi2::putScom (const fapi2::Target<TARGET_TYPE_XBUS> &i_target, const uint64_t i_address, buffer< uint64_t > &i_data) - { - // Do XBUS special code here. - } - -### How do I get <information> with the new targets when this used to be an attribute look up before? - -This question came up in the context of ATTR_CHIP_UNIT_POS, but really applies for any information -previously tucked away in attributes. - -Do the attribute lookup, the platform can optimize the look up away. In any event the get_attr macro/call will always do the right thing. - -If the platform can resolve the lookup without looking anything up (all the information is encoded in the value of the target) the attribute -mechanism can simply do that manipulation at compile time. - -For the smaller platforms, we discussed attribute look ups were templates which could be (would be?) specialized per attribute "key." -In this way, the "look up" for the unit position could be coded to be nothing more than a static manipulation of the target value. -A look up would, obviously, be needed if the unit position (or any other attribute value) couldn't be resolved from the target value alone. - -### Target Types - -#### How do I write a procedure which takes multiple target types? - -Depends on what you mean. - -##### If you mean "I have a procedure which is generic but only for a subset of types": - - fapi2::ReturnCode newProcedure( const fapi2::Target<TARGET_TYPE_XBUS | TARGET_TYPE_ABUS> & i_target, ...); - -Note that newProcedure can not then say "if xbus, do this, if abus do the -other." This is the static equivilent of grabbing a "base class" and the same -rules apply - if the method is not generic for all the subclasses, you need to -specialize for those subclasses. - -__Think twice about using this mechanism. It creates a new type (the or of the -target types) and reduces the input to this type. There is no support for run -time type conversion, and so the original type is not available in this scope.__ - -##### If you mean "I have a procedure and I want it to do different things for different target types": - -You can create templates: - - template<fapi2::TargetType T> - void newProcedure( const fapi2::Target<T>& i_target ); - - template<> - void newProcedure( const fapi2::Target<TARGET_TYPE_XBUS>& i_target ) - { - // XBUS specific code here - } - - template<> - void newProcedure( const fapi2::Target<TARGET_TYPE_ABUS>& i_target ) - { - // ABUS specific code here - } - -Notice that because the generic case for newProcedure is declared but -never defined you will get an error at compile time if newProcedure is -called with a type other than XBUS or ABUS. - -Or overloaded functions: - - void newProcedure( const fapi2::Target<TARGET_TYPE_XBUS>& i_target ) - { - // XBUS specific code here - } - - void newProcedure( const fapi2::Target<TARGET_TYPE_ABUS>& i_target ) - { - // ABUS specific code here - } - -##### If you mean "I have a procedure which is mostly generic but I need special handling for some target types": - -More or less the same as above, but define the generic template. There is no equivilent for -overloaded functions unless a composite target will suit your needs. - - template<fapi2::TargetType T> - void newProcedure( const fapi2::Target<T>& i_target ) - { - // Code for types other than ABUS or XBUS - } - - template<> - void newProcedure( const fapi2::Target<TARGET_TYPE_XBUS>& i_target ) - { - // XBUS specific code here - } - - template<> - void newProcedure( const fapi2::Target<TARGET_TYPE_ABUS>& i_target ) - { - // ABUS specific code here - } - -##### If you want to build a procedure which takes all target types: - -__It is recomended that you do not use TARGET_TYPE_ALL - that will reduce the -type of the passed in target to the "top level base class" of targets and -every procedure called will need to be completly generic. This is probably -not what you inteded (but is sometimes useful.) Rather, it is recomended -that you simply make a generic template.__ - - template<fapi2::TargetType T> - void newProcedure( const fapi2::Target<T>& i_target ) - { - // Code for all types - fapi2::putScom(i_target, ... ); - } - -Note that the putScom here will always be the correct putScom for the -target type passed in. Assuming procedures called in this method have -been specialized for specific target types, the compiler will find the -best match and call it. - -#### Once I'm in newProcedure, what is the type of the target? - -If you used a generic or specialized template, the type will be the type -of the target passed in. If you used a composite type (or'd together target -types) then the type will be TYPE_A | TYPE_B. - -Notice there's no simple way to know the original type was TYPE_A in this -case. If you think about this, it makes sense. Consider: - - void f(double x); - - int y = 3; - f(y); - -There's no way in f() to know that x started life as an int, which happened to -be cast to a double. - -Targets are the same thing - they're just types we create on the fly. So all of -the usual C++ tools to deal with this are available. - -#### So, wait - I can't write a procedure which handles multiple target types? - -You can. What you can't do is figure out the type of the object prior to -the cast. So what you need to do is make sure the original type isn't lost, -and that means you can't use TYPE_A | TYPE_B: - -##### Specialize. This is the prefered mechanism. -The template and overload examples above show how to do this specialization. -It will create very regular and easy to maintain code. - -##### Create a generic template and handle each type yourself. - - template<fapi2::TargetType T> - void newProcedure( fapi2::Target<T> i_target ) - { - // If this procedure isn't generic, check for allowed types here. - static_assert(fapi2::is_same<T, fapi2::TARGET_TYPE_ABUS>() || fapi2::is_same<T, fapi2::TARGET_TYPE_XBUS>(), - "newProcedure only takes X/A busses"); - - : - : - - if (fapi2::is_same<T, fapi2::TARGET_TYPE_ABUS>()) - { - // ABUS code - } - - if (fapi2::is_same<T, fapi2::TARGET_TYPE_XBUS>()) - { - // XBUS code - } - - : - : - } - -newProcedure is a generic template, any target type will match. And, the type T of i_target is -the original value of the target - the template matched without a cast because it's generic. -However, with that generality we lost the compiler argument type checking so we replace it with -the static_assert. This happens at compile time so the compiler will complain if a target other -than an XBUS or ABUS is passed in to this procedure. To handle the special cases for the types, -fapi2::is_same is used again - and is also a compile time operation. And so when this template -matches an XBUS target, the code generated is specific to the XBUS target. - -#### Ok, so what is TARGET_TYPE_X | TARGET_TYPE_Y for then? - -Creating procedures which are generic to those types. Think of this as a base -class method. diff --git a/src/ppe/hwpf/fapi/docs/topics/Ffdc.md b/src/ppe/hwpf/fapi/docs/topics/Ffdc.md deleted file mode 100755 index 85d696b..0000000 --- a/src/ppe/hwpf/fapi/docs/topics/Ffdc.md +++ /dev/null @@ -1,149 +0,0 @@ - -# Using the FFDC/XML Error Parsing Tools - -For FAPI2, the parseErrorInfo PERL script has changed. The main goal was to -enable FFDC generation classes/methods. This enables a named-parameter -model as well as tucking the FFDC generation into a container which can -easily be used by the FAPI_ASSERT macro. - -## Using the Tools - -parseErrorInfo.pl [--empty-ffdc-classes] [--use-variable-buffers] --output-dir=<output dir> <filename1> <filename2> ... -- This perl script will parse HWP Error XML files and creates the following files: -- hwp_return_codes.H. HwpReturnCode enumeration (HWP generated errors) -- hwp_error_info.H. Error information (used by FAPI_SET_HWP_ERROR when a HWP generates an error) -- collect_reg_ffdc.C. Function to collect register FFDC -- set_sbe_error.H. Macro to create an SBE error - -The --empty-ffdc-classes option is for platforms which don't collect FFDC. It will generate stub classes which -will allow the source to have the same code, but compile to no-ops on certain platforms. - -The --use-variable-bufers option is for platforms which support variable buffers. - -The XML input is the same format as for P8 - -## Using the Generated Classes - -Each error found in the XML files generates a class in hwp_ffdc_classes.H. -The name of the class is the same as the return code itself (lower case) -and the set methods are the same as the elements the xml described as -needing colletion. - -Take for example RC_MBVPD_INVALID_MT_DATA. Here is the XML: - - <hwpError> - <rc>RC_MBVPD_INVALID_MT_DATA</rc> - <description> - To get the proper MT data, we need a valid - dimm rank combination. - </description> - <ffdc>RANK_NUM</ffdc> - <callout> - <procedure>CODE</procedure> - <priority>HIGH</priority> - </callout> - </hwpError> - -It generates an FFDC class which looks like this (simplified): - - class rc_mbvpd_invalid_mt_data - { - public: - rc_mbvpd_invalid_mt_data( ... ) - { FAPI_ERR("To get the proper MT data, we need a valid dimm rank combination."); } - - rc_mbvpd_invalid_mt_data& set_rank_num(const T& i_value) - { <setup ffdc> } - - void execute(void) - { - FAPI_SET_HWP_ERROR(..., RC_MBVPD_INVALID_MT_DATA); - fapi2::logError( ... ); - } - }; - -To use this, for example, you may do: - - FAPI_ASSERT( foo != bar, - rc_mbvpd_invalid_mt_data().set_rank_num(l_rank), - "foo didn't equal bar" ); - -Notice the description of the error is automatically logged. - -## Buffer Support - -In FAPI, a ReturnCode had a mechanism for "containing" an error from an -ecmdDataBuffer. The API, setEcmdError(), no longer exists. fapi2::buffers -return ReturnCodes, and as such the FFDC information is added in a manner -consistent with the rest of the FFDC gathering. - -There is a new error xml file specifically for buffers called -buffer_error.xml. It will generate an FFDC class which will take a buffer -as an argument and generate the correct FFDC. - - <hwpError> - <rc>RC_FAPI2_BUFFER</rc> - <description> - fapi2 error from a buffer operation - </description> - <buffer>BUFFER</buffer> - <callout> - <procedure>CODE</procedure> - <priority>HIGH</priority> - </callout> - </hwpError> - -And its FFDC class: - - class rc_fapi2_buffer - { - public: - rc_fapi2_buffer( ... ) - { FAPI_ERR("fapi2 error from a buffer operation"); } - - rc_fapi2_buffer& set_buffer(const fapi2::variable_buffer& i_value) - { ... } - - template< typename T > - rc_fapi2_buffer& set_buffer(const fapi2::buffer<T>& i_value) - { ... } - }; - -And it can be used: - - fapi2::buffer<uint64_t> foo; - fapi2::variable_buffer bar; - - FAPI_ASSERT( rc != FAPI2_RC_SUCCESS, - rc_fapi2_buffer().set_fapi2_buffer(foo), - "problem with buffer" ); - - FAPI_ASSERT( rc != FAPI2_RC_SUCCESS, - rc_fapi2_buffer().set_fapi2_buffer(bar), - "problem with buffer" ); - -Note the indifference to integral or variable buffers. - -## Error Log Generation - -FAPI had a function called fapiLogError() which would generate platform -errors. The pattern was to call fapiLogError() at the end of the block -which generated the FFDC. With the addition of the FFDC classes, this -is no longer needed - the class knows to create these logs for you. - -However, the severity information is needed by this logging mechanism. -It was an argument to fapiLogError(), and so it's been added to the -constructor of the FFDC class: - -rc_repair_ring_invalid_ringbuf_ptr(fapi2::errlSeverity_t i_sev, ...) - -It defaults to "unrecoverable" and so only need be set for errors -which have a different severity. That is, doing nothing will get you -and error log with unrecoverable severity - which was the default -for FAPI. - -## Known Limitations - -- Collecting register FFDC is not presently implemented. -- Calling out to hwp to collect FFDC is not presently implemented. -- The FirstFailureData class does not have a platform pointer
\ No newline at end of file diff --git a/src/ppe/hwpf/fapi/docs/topics/README.md b/src/ppe/hwpf/fapi/docs/topics/README.md deleted file mode 100755 index ee7a9f0..0000000 --- a/src/ppe/hwpf/fapi/docs/topics/README.md +++ /dev/null @@ -1,166 +0,0 @@ - -# FAPI 2 and FAPI Lite definitions for targets, buffers, error handling. - -## Were are some examples? - -Examples can be found in the "Related Pages" tab. These examples are constantly -being expanded, please check back often. - -## How is the code structured? - -There is a new namespace; fapi2. This was created to prevent -the FAPI 1 code, in the fapi namespace, from colliding with the new code. - -- Most documentation can be found under the class definition. -- Documentation for FAPI_TRY/FAPI_ASSERT is in the file error_scope.H, - and doesn't have a "tab" in the HTML like the classes and the namespaces do. -- The documentation for TargeType is in the fapi namespace section. - -## What do I need to implement for my platform? - -### fapi2::buffer and fapi2::variable_buffer -There should be nothing for platforms to implement in the buffer code. -Smaller platforms which use fapi2::variable_buffer will need to -ensure they have an implementation of std::vector. Hostboot has one -which I'm sure you can steal if needed. - -### fapi2::Target and fapi2::TargetType -Target is defined as a template of <TargetType, Value> where -Value is defined per platform. Smaller platforms will want an integer -type here, say uint64_t. Larger platforms may want to change this to -a pointer to an underlying platform specific targeting object. - -The target traversing functions will need to be implemented per-platform. - -### Hardware Access (fapi2::getScom() ...) - -All of the hardware access functions are assumed to need implementation -per platform. - -Please use template specialization for target types which need special -treatment. The API documented here are generic, but they can be made -very specific for a target type or composite type. - -For example (perhaps a poor example ...) - - template< TargetType K > - ReturnCode getScom(const Target<K>& i_target, const uint64_t i_address, - buffer<uint64_t>& o_data) -can become - - template<> - ReturnCode getScom(const Target<TARGET_TYPE_DIMM>& i_target, const uint64_t i_address, - buffer<uint64_t>& o_data) -for DIMMs - -or - - template<> - ReturnCode getScom(const Target<TARGET_TYPE_XBUS | TARGET_TYPE_ABUS>& i_target, const uint64_t i_address, - buffer<uint64_t>& o_data) - -for XBUS and ABUS - -### fapi2::ReturnCode and error_scope.H - -For smaller platforms, a fapi::ReturnCode is nothing but a uint64_t. For -larger platforms fapi2::ReturnCode inherits from a (TBD) FFDC object. - -There should be nothing to do for error_scope.H - -### fapi2::FirstFailureData (FFDC (work in progress)) - -The platform specific FFDC object will need to be implemented, but the -tooling to generate the FFDC functions used in FAPI_ASSERT will be provided. - -### Attributes - -As in FAPI 1, platforms will need to implement the mechanism behind the -ATTR_GET/SET macros. - -## How to report an issue? - -Something in here is wrong - I'm sure of it. But you found it before someone -else. Please don't fire off an email into the ether; it will get lost. -Report an issue. Issues can be tracked and you can see what other issues are -taking priority over yours, etc. It's just better for everyone. - -__To report an issue use Clear Quest__ - - Tier: ip Firmware - - Reported Release: FW910 - - Subsystem: Hostboot - - Component: FAPI - -## Not sure how to do something? - -So you've read the API documentation and it's horrible. You can't figure -out how to get anything done. Could be an issue, could be you just need the -crazy engineer who specified this horrible mess to see what struggles they -created in their overzealous attempt to make things "simple." - -__Put it on the wiki__ - -You could send someone an email, and that might work out great. But if you -use the wiki you can be abrasive with your comments! Others might be able -to help or offer an opinion or become a member of the virtual posse you're -gathering to track down the crazy engineer. Good fun? You need a hobby. - -None the less, the crazy engineer should update the FAPI 2 documentation when -the best practice is worked out, or create an issue to track the change -(and add it to a test case.) - -Examples can be found in the "Related Pages" tab. - -Questions have been asked as topics on the PFD/HW for P9 community wiki. - -## Something missing? Before you report an issue ... - -Many of the API from FAPI 1 have been changed into templated functions. For -example, - - ecmdDataBuffer::getDoubleWordLength() -> fapi::buffer::getLength<uint64_t>() - ecmdDataBuffer::getWordLength() -> fapi::buffer::getLength<uint32_t>() - ecmdDataBuffer::getHalfWordLength() -> fapi::buffer::getLength<uint16_t>() - -Some API have been deprecated in favor of other API, some API have been -deprecated and are waiting for a use-case, and they'll be implemented. -A list of deprecated ecmdDataBuffer functions can be found in the -fapi::buffer_base class documentation. - -Some API have been removed/deprecated and are expected to return in a different -form once the requirements are understood. Examples of this are the compressed -fapi::buffers. While platforms may need these functions, they have been removed -from the class itself as they are not vital to the class operation. These -functions, as needed, will be replaced with utility functions which perform the -operations needed for the platform. An example is fapi::Target::toString. -It has been replaced with fapi::toString(Target, ...) which can be overloaded -to take any type, and makes a nice utility for the fapi namespace. - -Some API have plum been forgotten. You should open an issue so we can track -the implementation. - -## Where's the documentation for Attributes? - -The attribute macros are not expected to change for FAPI 2: - - l_rc = FAPI_ATTR_GET(<ID>, l_pTarget, l_val); - l_rc = FAPI_ATTR_SET(<ID>, l_pTarget, l_val); - l_rc = FAPI_ATTR_GET_PRIVILEGED(<ID>, l_pTarget, l_val); - l_rc = FAPI_ATTR_SET_PRIVILEGED(<ID>, l_pTarget, l_val); - -There is one outstanding question: - 1. whether we should/can change from a pointer to a target to a reference - to a target to save a dereference on the smaller platforms (maybe it gets - optimized out anyway?) - - Seems like the answer will be "no," but this depends on the PPE attribute - look up scheme I think. Work in Progress. - -## Where's the FFDC documentation? - -Currently scheduled for End of February, 2015. - -## Other Known Issues - -- Thread local storage is broken on gcc 4.8, and the thread_local variables in -error_scope.H will need to become pthread TLS for the time being. |
