From: E. Scott Daniels Date: Fri, 19 Apr 2019 19:51:41 +0000 (+0000) Subject: feat(doc): Add trace man pages X-Git-Tag: 1.0.31~34 X-Git-Url: https://gerrit.o-ran-sc.org/r/gitweb?a=commitdiff_plain;h=08aee4ae090afcf804aaa33d219c224ac2e8d399;p=ric-plt%2Flib%2Frmr.git feat(doc): Add trace man pages Change-Id: I51493fc1322ffc07e1fc9a5e9be4f7ce54c88994 Signed-off-by: E. Scott Daniels --- diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index 44f0001..2dbca2b 100644 --- a/doc/CMakeLists.txt +++ b/doc/CMakeLists.txt @@ -73,6 +73,11 @@ if( BUILD_DOC ) rmr_support.3 rmr_torcv_msg.3 rmr_wh_send_msg.3 + rmr_get_trace.3 + rmr_init_trace.3 + rmr_set_trace.3 + rmr_tralloc_msg.3 + rmr_get_trlen.3 ) # empty list of roff/troff input files we generated diff --git a/doc/src/man/rmr.7.xfm b/doc/src/man/rmr.7.xfm index 4c3e13a..eab9b9a 100644 --- a/doc/src/man/rmr.7.xfm +++ b/doc/src/man/rmr.7.xfm @@ -113,9 +113,13 @@ and the defaults which RMr uses if undefined. &h2(SEE ALSO ) .ju off rmr_alloc_msg(3), +rmr_tralloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3), +rmr_init_trace(3), +rmr_get_trace(3), +rmr_get_trlen(3), rmr_payload_size(3), rmr_rcv_msg(3), rmr_rcv_specific(3), @@ -126,6 +130,7 @@ rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3), rmr_ring_free(3), +rmr_set_trace(3), rmr_torcv_msg(3), rmr_wh_open(3), rmr_wh_send_msg(3) diff --git a/doc/src/man/rmr_alloc_msg.3.xfm b/doc/src/man/rmr_alloc_msg.3.xfm index 04b908b..a9dad95 100644 --- a/doc/src/man/rmr_alloc_msg.3.xfm +++ b/doc/src/man/rmr_alloc_msg.3.xfm @@ -48,7 +48,7 @@ &ex_start #include -rmr_mbuf_t* rmr_alloc_msg( void* a, int size ); +rmr_mbuf_t* rmr_alloc_msg( void* ctx, int size ); &ex_end &uindent @@ -59,7 +59,7 @@ The buffer is allocated such that sending it requires no additional copying out of the buffer. If the value passed in &cw(size) is 0, then the default size supplied on the &ital(rmr_init) call will be used. -The &ital(a) parameter is the void context pointer that was returned by +The &ital(ctx) parameter is the void context pointer that was returned by the &ital(rmr_init) function. &space @@ -74,7 +74,7 @@ typedef struct { int mtype; int len; unsigned char* payload; - unsigned char* a; + unsigned char* xaction; } rmr_mbuf_t; &ex_end @@ -113,12 +113,12 @@ should &bold(NOT) make use of the payload pointer. &half_space -&ditem(a ) The &ital(a) field is a pointer to a fixed sized area in +&ditem(xaction) The &ital(xaction) field is a pointer to a fixed sized area in the message into which the user may write a transaction ID. The ID is optional with the exception of when the user application uses the &cw(rmr_call) function to send a message and wait for the reply; the underlying RMR processing expects that the matching reply message will also contain the same data in the -&ital(a) field. +&ital(xaction) field. &end_dlist &h2(RETURN VALUE) @@ -132,10 +132,13 @@ The function returns a pointer to a &cw(rmr_mbuf) structure, or NULL on error. .** &h2(EXAMPLE) &h2(SEE ALSO ) -rmr_mbuf(3) +rmr_tralloc_msg(3), rmr_call(3), rmr_free_msg(3), rmr_init(3), +rmr_init_trace(3), +rmr_get_trace(3), +rmr_get_trlen(3), rmr_payload_size(3), rmr_send_msg(3), rmr_rcv_msg(3), @@ -146,8 +149,8 @@ rmr_fib(3), rmr_has_str(3), rmr_tokenise(3), rmr_mk_ring(3), -rmr_ring_free(3) - +rmr_ring_free(3), +rmr_set_trace(3) .qu diff --git a/doc/src/man/rmr_get_trace.3.xfm b/doc/src/man/rmr_get_trace.3.xfm new file mode 100644 index 0000000..70417c9 --- /dev/null +++ b/doc/src/man/rmr_get_trace.3.xfm @@ -0,0 +1,101 @@ +.if false +================================================================================== + Copyright (c) 2019 Nokia + Copyright (c) 2018-2019 AT&T Intellectual Property. + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +================================================================================== +.fi + +.if false + Mnemonic rmr_get_trace.3.xfm + Abstract The manual page for the rmr_get_trace function. + Author E. Scott Daniels + Date 19 April 2019 +.fi + +.** if formatting with tfm, the roff.im will cause roff output to be generated +.** if formatting with pfm, then pretty postscript will be generated +.gv e LIB lib +.if pfm + .im &{lib}/generic_ps.im +.ei + .gv e OUTPUT_RST use_rst + .if .ev &use_rst 1 = + .im &{lib}/rst.im + .ei + .im &{lib}/roff.im + .fi +.fi + +&line_len(6i) + +&h1(RMR Library Functions) +&h2(NAME) + rmr_get_trace + +&h2(SYNOPSIS) +&indent +&ex_start +#include + +int rmr_get_trace( rmr_mbuf_t* mbuf, unsigned char* dest, int size ) +&ex_end + +&uindent + +&h2(DESCRIPTION) +The &cw(rmr_get_trace) function will copy the trace information from the message into the user's +allocated memory referenced by &cw(dest.) +The &cw(size) parameter is assumed to be the maximum number of bytes which can be copied (size +of the destination buffer). + +&h2(RETURN VALUE) +On success, the number of bytes actually copied is returned. +If the return value is 0, no bytes copied, then the reason could be that the message pointer +was nil, or the size parameter was <= 0. + + +&h2(SEE ALSO ) +.ju off +rmr_alloc_msg(3), +rmr_tralloc_msg(3), +rmr_bytes2xact(3), +rmr_bytes2meid(3), +rmr_call(3), +rmr_free_msg(3), +rmr_get_rcvfd(3), +rmr_get_trlen(3), +rmr_init(3), +rmr_init_trace(3), +rmr_payload_size(3), +rmr_send_msg(3), +rmr_rcv_msg(3), +rmr_rcv_specific(3), +rmr_rts_msg(3), +rmr_ready(3), +rmr_fib(3), +rmr_has_str(3), +rmr_tokenise(3), +rmr_mk_ring(3), +rmr_ring_free(3), +rmr_str2meid(3), +rmr_str2xact(3), +rmr_wh_open(3), +rmr_wh_send_msg(3), +rmr_set_trace(3) +.ju on + + +.qu + diff --git a/doc/src/man/rmr_get_trlen.3.xfm b/doc/src/man/rmr_get_trlen.3.xfm new file mode 100644 index 0000000..1f0d774 --- /dev/null +++ b/doc/src/man/rmr_get_trlen.3.xfm @@ -0,0 +1,92 @@ +.if false +================================================================================== + Copyright (c) 2019 Nokia + Copyright (c) 2018-2019 AT&T Intellectual Property. + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +================================================================================== +.fi +.if false + Mnemonic rmr_get_trlen + Abstract The manual page for the get trace len function. + Author E. Scott Daniels + Date 19 April 2019 +.fi + +.** if formatting with tfm, the roff.im will cause roff output to be generated +.** if formatting with pfm, then pretty postscript will be generated +.gv e LIB lib +.if pfm + .im &{lib}/generic_ps.im +.ei + .gv e OUTPUT_RST use_rst + .if .ev &use_rst 1 = + .im &{lib}/rst.im + .ei + .im &{lib}/roff.im + .fi +.fi + + +&line_len(6i) + +&h1(RMR Library Functions) +&h2(NAME) + rmr_get_trlen + +&h2(SYNOPSIS ) +&indent +&ex_start +#include + +int rmr_get_trlen( rmr_mbuf_t* msg ); +&ex_end +&uindent + +&h2(DESCRIPTION) +Given a message buffer, this function returns the amount of space (bytes) +that have been allocated for trace data. +If no trace data has been allocated, then 0 is returned. + +&h2(RETURN VALUE) +The number of bytes allocated for trace information in the given message. + +&h2(ERRORS) +&beg_dlist(.75i : ^&bold_font ) +&di(INVAL) Parameter(s) passed to the function were not valid. +&end_dlist + + +&h2(SEE ALSO ) +rmr_alloc_msg(3), +rmr_call(3), +rmr_free_msg(3), +rmr_get_trace(3), +rmr_init(3), +rmr_init_trace(3), +rmr_send_msg(3), +rmr_rcv_msg(3), +rmr_rcv_specific(3), +rmr_rts_msg(3), +rmr_ready(3), +rmr_fib(3), +rmr_has_str(3), +rmr_tokenise(3), +rmr_mk_ring(3), +rmr_ring_free(3), +rmr_set_trace(3), +rmr_tralloc_msg(3) + + +.qu + diff --git a/doc/src/man/rmr_init_trace.3.xfm b/doc/src/man/rmr_init_trace.3.xfm new file mode 100644 index 0000000..8d6b1da --- /dev/null +++ b/doc/src/man/rmr_init_trace.3.xfm @@ -0,0 +1,105 @@ +.if false +================================================================================== + Copyright (c) 2019 Nokia + Copyright (c) 2018-2019 AT&T Intellectual Property. + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +================================================================================== +.fi + +.if false + Mnemonic rmr_init_trace_man.xfm + Abstract The manual page for the rmr_init_trace function. + Author E. Scott Daniels + Date 19 April 2019 +.fi + +.** if formatting with tfm, the roff.im will cause roff output to be generated +.** if formatting with pfm, then pretty postscript will be generated +.gv e LIB lib +.if pfm + .im &{lib}/generic_ps.im +.ei + .gv e OUTPUT_RST use_rst + .if .ev &use_rst 1 = + .im &{lib}/rst.im + .ei + .im &{lib}/roff.im + .fi +.fi + +&line_len(6i) + +&h1(RMR Library Functions) +&h2(NAME) + rmr_init_trace + +&h2(SYNOPSIS) +&indent +&ex_start +#include + +void* rmr_init_trace( void* ctx ) +&ex_end + +&uindent + +&h2(DESCRIPTION) +The &cw(rmr_init_trace) function establishes the default trace space placed in each +message buffer allocated with &cw(rmr_alloc_msg().) +If this function is never called, then no trace space is allocated by default into +any message buffer. + +.sp +Trace space allows the user application to pass some trace token, or other data +with the message, but outside of the payload. +Trace data may be added to any message with &cw(rmr_set_trace(),) and may be extracted +from a message with &cw(rmr_get_trace().) +The number of bytes that a message contains for/with trace data can be determined by +invoking &cw(rmr_get_trlen().) + +.sp +This function may be safely called at any time during the life of the user programme +to (re)set the default trace space reserved. +If the user programme needs to allocate a message with trace space of a different +size than is allocated by default, without fear of extra overhead of reallocating +a message later, the &cw(rmr_tralloc_msg()) function can be used. + +&h2(RETURN VALUE) +A value of 1 is returned on success, and 0 on failure. A failure indicates that the +RMr context (void *) passed to this function was not valid. + +&h2(SEE ALSO ) +rmr_alloc_msg(3), +rmr_tr_alloc_msg(3), +rmr_call(3), +rmr_free_msg(3), +rmr_get_rcvfd(3), +rmr_get_trace(3), +rmr_get_trlen(3), +rmr_payload_size(3), +rmr_send_msg(3), +rmr_rcv_msg(3), +rmr_rcv_specific(3), +rmr_rts_msg(3), +rmr_ready(3), +rmr_fib(3), +rmr_has_str(3), +rmr_tokenise(3), +rmr_mk_ring(3), +rmr_ring_free(3), +rmr_set_trace(3) + + +.qu + diff --git a/doc/src/man/rmr_set_trace.3.xfm b/doc/src/man/rmr_set_trace.3.xfm new file mode 100644 index 0000000..2ee05ba --- /dev/null +++ b/doc/src/man/rmr_set_trace.3.xfm @@ -0,0 +1,102 @@ +.if false +================================================================================== + Copyright (c) 2019 Nokia + Copyright (c) 2018-2019 AT&T Intellectual Property. + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +================================================================================== +.fi + +.if false + Mnemonic rmr_set_trace.xfm + Abstract The manual page for the rmr_set_trace function. + Author E. Scott Daniels + Date 19 April 2019 +.fi + +.** if formatting with tfm, the roff.im will cause roff output to be generated +.** if formatting with pfm, then pretty postscript will be generated +.gv e LIB lib +.if pfm + .im &{lib}/generic_ps.im +.ei + .gv e OUTPUT_RST use_rst + .if .ev &use_rst 1 = + .im &{lib}/rst.im + .ei + .im &{lib}/roff.im + .fi +.fi + +&line_len(6i) + +&h1(RMR Library Functions) +&h2(NAME) + rmr_set_trace + +&h2(SYNOPSIS) +&indent +&ex_start +#include + +int rmr_bytes2payload( rmr_mbuf_t* mbuf, unsigned char* data, int len ) +&ex_end + +&uindent + +&h2(DESCRIPTION) +The &cw(rmr_set_trace) function will copy &cw(len) bytes from &cw(data) into the trace portion of +&cw(mbuf.) +If the trace area of &cw(mbuf) is not the correct size, the message buffer will be reallocated +to ensure that enough space is available for the trace data. + + +&h2(RETURN VALUE) +The &cw(rmr_set_trace) function returns the number of bytes successfully copied to the message. +If 0 is returned either the message pointer was nil, or the size in the parameters was <= 0. + + + +&h2(SEE ALSO ) +rmr_alloc_msg(3), +rmr_tralloc_msg(3), +rmr_bytes2xact(3), +rmr_bytes2payload(3), +rmr_call(3), +rmr_free_msg(3), +rmr_get_rcvfd(3), +rmr_get_meid(3), +rmr_get_trace(3), +rmr_get_trlen(3), +rmr_init(3), +rmr_init_trace(3), +rmr_payload_size(3), +rmr_send_msg(3), +rmr_rcv_msg(3), +rmr_rcv_specific(3), +rmr_rts_msg(3), +rmr_ready(3), +rmr_fib(3), +rmr_has_str(3), +rmr_tokenise(3), +rmr_mk_ring(3), +rmr_ring_free(3), +rmr_str2meid(3), +rmr_str2xact(3), +rmr_wh_open(3), +rmr_wh_send_msg(3) + + + +.qu + diff --git a/doc/src/man/rmr_tralloc_msg.3.xfm b/doc/src/man/rmr_tralloc_msg.3.xfm new file mode 100644 index 0000000..64a0d72 --- /dev/null +++ b/doc/src/man/rmr_tralloc_msg.3.xfm @@ -0,0 +1,166 @@ +.if false +================================================================================== + Copyright (c) 2019 Nokia + Copyright (c) 2018-2019 AT&T Intellectual Property. + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +================================================================================== +.fi +.if false + Mnemonic rmr_tralloc_msg.xfm + Abstract The manual page for the rmr_tralloc_msg function. + Author E. Scott Daniels + Date 19 April 2019 +.fi + +.** if formatting with tfm, the roff.im will cause roff output to be generated +.** if formatting with pfm, then pretty postscript will be generated +.gv e LIB lib +.if pfm + .im &{lib}/generic_ps.im +.ei + .gv e OUTPUT_RST use_rst + .if .ev &use_rst 1 = + .im &{lib}/rst.im + .ei + .im &{lib}/roff.im + .fi +.fi + +&line_len(6i) + +&h1(RMR Library Functions) +&h2(NAME) + rmr_tralloc_msg + +&h2(SYNOPSIS ) +&indent +&ex_start +#include + +rmr_mbuf_t* rmr_tralloc_msg( void* vctx, int size, + int trace_size, unsigned const char *tr_data ); +&ex_end +&uindent + +&h2(DESCRIPTION) +The &cw(rmr_alloc_msg) function is used to allocate a buffer which the user +programme can write into and then send through the a library. +The buffer is allocated such that sending it requires no additional copying +from the buffer as it passes through the underlying transport mechanism. +.sp + +The &ital(size) parameter is used to set the payload length in the message and +If it is 0, then the default size supplied on the &ital(rmr_init) call will be used. +In addition to allocating the payload, a space in the buffer is +reserved for &ital(trace) data (tr_size bytes), and the bytes pointed to +by &ital(tr_data) are copied into that portion of the message. + +The &ital(vctx) parameter is the void context pointer that was returned by +the &ital(rmr_init) function. + + +&space +The pointer to the message buffer returned is a structure which has some +user application visible fields; the structure is described in &cw(rmr.h,) +and is illustrated below. + +&space +&ex_start +typedef struct { + int state; + int mtype; + int len; + unsigned char* payload; + unsigned char* xaction; +} rmr_mbuf_t; +&ex_end + +&space +&beg_dlist(.75i : ^&bold_font ) +&ditem(state ) Is the current buffer state. Following a call to &cw(rmr_send_msg) +the state indicates whether the buffer was successfully sent which determines +exactly what the payload points to. If the send failed, the payload referenced +by the buffer is the message that failed to send (allowing the application to +attempt a retransmission). +When the state is &cw(a_OK) the buffer represents an empty buffer that the application +may fill in in preparation to send. + +&half_space +&ditem(mtype ) When sending a message, the application is expected to set this field +to the appropriate message type value (as determined by the user programme). Upon send +this value determines how the a library will route the message. +For a buffer which has been received, this field will contain the message type that was +set by the sending application. + +&half_space +&ditem(len ) The application using a buffer to send a message is expected to set the +length value to the actual number of bytes that it placed into the message. This +is likely less than the total number of bytes that the message can carry. +For a message buffer that is passed to the application as the result of a receive +call, this will be the value that the sending application supplied and should +indicate the number of bytes in the payload which are valid. + +&half_space +&ditem(payload ) The payload is a pointer to the actual received data. The +user programme may read and write from/to the memory referenced by the payload +up until the point in time that the buffer is used on a &cw(rmr_send, rmr_call) +or &cw(rmr_reply) function call. +Once the buffer has been passed back to a a library function the user programme +should &bold(NOT) make use of the payload pointer. + + +&half_space +&ditem(xaction) The &ital(xaction) field is a pointer to a fixed sized area in +the message into which the user may write a transaction ID. +The ID is optional with the exception of when the user application uses the &cw(rmr_call) +function to send a message and wait for the reply; the underlying a processing +expects that the matching reply message will also contain the same data in the +&ital(xaction) field. +&end_dlist + +&h2(RETURN VALUE) +The function returns a pointer to a &cw(rmr_mbuf) structure, or NULL on error. + +&h2(ERRORS) +&beg_dlist(.75i : ^&bold_font ) +&di(ENOMEM) Unable to allocate memory. +&end_dlist + +.** &h2(EXAMPLE) + +&h2(SEE ALSO ) +rmr_alloc_msg(3), +rmr_mbuf(3) +rmr_call(3), +rmr_free_msg(3), +rmr_init(3), +rmr_init_trace(3), +rmr_get_trace(3), +rmr_get_trlen(3), +rmr_payload_size(3), +rmr_send_msg(3), +rmr_rcv_msg(3), +rmr_rcv_specific(3), +rmr_rts_msg(3), +rmr_ready(3), +rmr_fib(3), +rmr_has_str(3), +rmr_tokenise(3), +rmr_mk_ring(3), +rmr_ring_free(3), +rmr_set_trace(3) + + +.qu +